16 Push Notifications

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

This chapter includes the following sections:

Section 16.1, "Introduction to Push Notifications"
Section 16.2, "Enabling Push Notifications for an ADF Mobile Application"
Section 16.3, "About the Push Notification Payload"

16.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 16-1 shows a push notification alert on an iOS-powered device.

Figure 16-1 A Push Notification

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.

16.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. 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.

16.1.2 How ADF Mobile Applications Display Notifications Depending on Application State

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.

16.2 Enabling Push Notifications for an ADF Mobile Application

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());
```

16.3 About the Push Notification Payload

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.