17 Enabling Push Notifications

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.

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