Fusion Middleware Documentation
Advanced Search


Oracle Enterprise Pack for Eclipse Developing Mobile Applications with Oracle Mobile Application Framework (OEPE Edition)
Close Window

Table of Contents

Show All | Collapse

17 Enabling Push Notifications

This chapter describes how to enable mobile applications to register for, and handle, push notification messages.

This chapter includes the following sections:

17.1 Introduction to Push Notifications

Push notifications are notifications sent from an external source, such as a server, to an application on a mobile device. These may appear as messages in the form of an alert, or as a banner, depending on the state of the application and user settings. Figure 17-1 shows a push notification alert on an iOS-powered device.

Figure 17-1 A Push Notification

This image is described in the surrounding text

When users are notified, they can launch the application, or they can choose to ignore the notification. In this case, the application is not activated. Notifications may also accompany an alert message with a brief, distinctive sound.

17.1.1 How Push Notifications Work

Applications must register with a notification service to receive push notifications. If the registration succeeds, then the notification service issues a token to the application. The application shares this token with its provider (located on a remote server), and in doing so, enables the provider to send notifications to the application through the notification service. MAF registers on behalf of the application using application-provided registration configuration, described in Section 17.2, "Enabling Push Notifications for a Mobile Application." Registration occurs upon every start of the mobile application to ensure a valid token. After a successful registration, MAF shares the token obtained from the platform-specific notification service with the provider. On iOS, the notification service is Apple Push Notification Service (APNs). Google Cloud Messaging (GCM) for Android provides the notification service for applications installed on Android-powered devices.

17.1.2 How Mobile Applications Display Notifications Depending on Application State

A mobile application can receive push notifications regardless of its state; the display of these messages, which can appear even when the application is not in the foreground, depends on the state of the mobile application and the user settings. Table 17-1 describes how the iOS operating system handles push notifications depending on the state of the mobile application.

Table 17-1 Handling Push Notifications on an iOS-Powered Device

State Action

The mobile application is installed, but not running.

The notification message displays with the registered notification style (none, banner, or alert). When the user taps the message (if its a banner-style notification) or touches the action button (if the message appears as an alert), the mobile application launches, invoking the application notification handlers.

The mobile application is running in the background.

The notification message displays with the registered notification style (none, banner, alert). When the user taps the message (if it is a banner-style notification), or touches the action button (if the message appears as an alert), the mobile application launches, invoking the application notification handlers.

The mobile application is running in the foreground.

No notification message displays. The application notification handlers are invoked.


On the iOS and Android platforms, if the application is not running in the foreground, then any push notification messages associated with it are queued in a specific location, such as the iOS Notification Center or the notification drawer on Android-powered devices.

17.2 Enabling Push Notifications for a Mobile Application

You can enable push notifications by performing the following tasks:

  1. Allow the mobile application to receive push notifications by choosing Push notifications access in the Device Access section of the MAF Application Editor. For more information, see Section 21.6.1, "How to Enable Access to Device Capabilities."

    Note:

    By default, a mobile application does not allow push notifications (nor any other device type of device access).

  2. In the application controller project, register an application lifecycle event listener (ALCL) class. For more information, see Section 4.4, "Setting the Basic Information for a Mobile Application" and Section 4.8, "About Lifecycle Event Listeners."

  3. Implement the oracle.adfmf.application.PushNotificationConfig interface in the ALCL. This interface provides the configuration required to successfully register with the push notification service.

    Override and implement the getNotificationStyle and getSourceAuthorizationId methods of the PushNotificationConfig interface. The getNotificationStyle method enables you to specify the notification styles for which the application registers. The getSourceAuthorizationId method enables you to enter the Google Project Number of the accounts authorized to send messages to the mobile application. For more information, see Java API Reference for Oracle Mobile Application Framework.

  4. In the application controller project, create a push notification event listener class (for example, NativePushNotificationListener) that handles push notification events. This class must implement the oracle.adfmf.framework.event.EventListener interface that defines an event listener. For more information on the oracle.adfmf.framework.event.EventListener interface, see Java API Reference for Oracle Mobile Application Framework.

    Override and implement the onOpen, onMessage, and onError methods to register for and receive notification events. After a successful registration with the push notification service, MAF calls the onOpen method with the registration token that must be shared with the provider by the application developer. The onError method is invoked if there is an error when registering with the notification service, with the error returned by the push notification service encapsulated as an AdfException.

    MAF calls the onMessage(Event e) method with the notification payload whenever the application receives a notification. The Event object can be used to retrieve useful information about notification payload and the application state. To get the notification payload, use the Event.getPayload method. To get the application state at the time of notification, use the Event.getApplicationState method. For more information, see the Event class in Java API Reference for Oracle Mobile Application Framework.

  5. Get an EventSource object in the start method of the ALCL class that represents the source of a native push notification event:

    EventSource evtSource =
    EventSourceFactory.getEventSource(EventSourceFactory.NATIVE_PUSH_NOTIFICATION_
                                                                     REMOTE_EVENT
                                                                    _SOURCE_NAME);
    
  6. Create and add an object of the push notification events listener class to the event source:

    evtSource.addListener(new NativePushNotificationListener());
    

17.3 About the Push Notification Payload

MAF respects the following keys for a JSON-formatted payload:

  • alert: the text message shown in the notification prompt.

  • sound: a sound that is played when the notification is received.

  • badge: the number to badge the application icon on iOS.

    Note:

    On Android, the payload can be a JSON object with key-value pairs. The value is always converted to a string, because the GCM server converts non-string values to strings before sending them to an application. This is not the case with the APNs, which preserves the value types. For more information, refer to the description of the "data" message parameter in the "Implementing GCM Server" section of Google Cloud Messaging. This document is available from the Android Developers website (http://developer.android.com/index.html) or the Android SDK documentation.