This chapter describes how to enable ADF Mobile applications to register for, and handle, push notification messages.
This chapter includes the following sections:
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 16-1 shows a push notification alert on an iOS-powered device.
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.
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. ADF Mobile registers on behalf of the application using application-provided registration configuration, described in Section 16.2, "Enabling Push Notifications for an ADF Mobile Application." Registration occurs upon every start of the ADF Mobile application to ensure a valid token. After a successful registration, ADF Mobile 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.
An ADF 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 ADF Mobile application and the user settings. Table 16-1 describes how the iOS operating system handles push notifications depending on the state of the ADF Mobile application.
Table 16-1 Handling Push Notifications on an iOS-Powered Device
State | Action |
---|---|
The ADF 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 ADF Mobile application launches, invoking the application notification handlers. |
The ADF 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 ADF Mobile application launches, invoking the application notification handlers. |
The ADF 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.
You can enable push notifications by performing the following tasks:
In the application controller project, register an application lifecycle event listener (ALCL) class. For more information, see Section 5.3, "Setting the Basic Information for an ADF Mobile Application" and Section 5.7, "About Lifecycle Event Listeners."
Implement the oracle.adfmf.application.PushNotificationConfig
interface in the ALCL. This interface provides the registration configuration for push notifications.
Override and implement the getNotificationStyle
and getSourceAuthorizationID
methods of the PushNotificationConfig
interface. The getNotificationStyle
method enables you to style the notification per the iOS Settings application. The getSourceAuthorizationID
method enables you to enter the Google Project Number of the accounts authorized to send messages to the ADF Mobile application. For more information, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.
In the application controller project, create a push notification 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 Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.
Override and implement the onOpen
and onMessage
methods to handle notifications. After a successful registration with the push notification service, ADF Mobile calls onOpen
with the registration token that must be shared with the provider by the application developer. If there was an error registering with the notification service, the registration token would be a null
object.
ADF Mobile calls the onMessage
method with the notification payload whenever the application receives a notification.
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);
Create and add an object of the push notification listener class to the event source:
evtSource.addListener(new NativePushNotificationListener());
ADF Mobile 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.