24 Enabling and Using Notifications

This chapter describes how to enable MAF applications to display local notifications as well as register for, and handle, push notification messages.

This chapter includes the following sections:

24.1 Introduction to Notifications

Notifications are signals delivered to the end user outside of a mobile application's regular user interface. These notifications can appear as messages in the form of an alert, or as a banner, depending on the state of the application and user settings. The notifications may be presented visually or as a sound or both.

The following are the two main types of notifications:

  • Push notifications are sent from an external source, such as a server, to an application on a mobile device. When end users are notified, they can either launch the application or they can choose to ignore the notification in which case the application is not activated.

    Figure 24-1 shows a push notification alert on an iOS-powered device.

    Figure 24-1 Push Notification

    This image is described in the surrounding text

    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 24.2, "Enabling Push Notifications." Registration occurs upon every start of the MAF 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.

    A MAF 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 MAF application and the user settings. Table 24-1 describes how the iOS operating system handles push notifications depending on the state of the MAF application.

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

    State Action

    The MAF 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 MAF application launches, invoking the application notification handlers.

    The MAF 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 MAF application launches, invoking the application notification handlers.

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

  • Local notifications originate within a mobile application and are received by the same application. The notifications are delivered to the end user through standard mechanisms supported by the mobile device platform (for example, banner, sound).

    Using the Local Notification Abstraction API provided by MAF, you can configure the application to raise a notification immediately or schedule a notification for a future date and time. In addition, you can set a repeat pattern for a notification (for example, daily or weekly) as well as cancel a scheduled notification.

    On both the iOS and Android platform, if the MAF application is running in the foreground, the notification is delivered directly to the application without the end user interaction. If the application is either running in the background or not running at all, the notification is delivered to the application once the end user taps on the notification.

24.2 Enabling Push Notifications

You can enable push notifications by performing the following tasks:

  1. Allow the MAF application to receive push notifications by choosing Push Notifications in the Device Access page of the maf-application.xml overview editor, as shown in Figure 24-2.

    Note:

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

    Figure 24-2 Allowing Push Notifications

    This image is described in the surrounding text

  2. In the application controller project, register an application lifecycle event listener (ALCL) class. For more information, see Section 3.3, "Setting Display Properties for an Application Feature" and Chapter 11, "Using Lifecycle Listeners in MAF Applications."

  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 MAF application. For more information, see Oracle Fusion Middleware 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 Oracle Fusion Middleware 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 Oracle Fusion Middleware 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());

MAF sample applications called PushDemo and PushServer demonstrate how to handle push notifications. These sample applications are located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.

24.2.1 What You May Need to Know 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 stringified, 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 at http://developer.android.com/index.html or the Android SDK documentation.

24.3 Managing Local Notifications

You can manage local notifications by using the following:

A MAF sample application called LocalNotificationDemo demonstrates how to schedule and handle local notifications. This sample application is located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.

24.3.1 How to Manage Local Notifications Using Java

You can schedule local notifications using the following methods of the oracle.adfmf.framework.api.AdfmfContainerUtilities class:

  • addLocalNotification(MafNativeLocalNotificationOptions options). This method returns a String that represents the ID of the notification being scheduled.

    In your Java code, you use this method in a manner similar to the following:

    try {
  // Configure local notification
  MafNativeLocalNotificationOptions options =
                new MafNativeLocalNotificationOptions();

  options.setTitle("some title text");
  options.setAlert("some alert text");

  // Set the date in UTC
  options.setDate(LocalDateTime.now(Clock.systemUTC()).plusSeconds(5));
  // Set the notification to repeat every minute
  options.setRepeat(MafNativeLocalNotificationOptions.RepeatInterval.MINUTELY);
  // Set the application badge to be '1' everytime notification is triggered
  options.setBadge(1);
  // Play the default system sound when notification triggers
  options.setSound(MafNativeLocalNotificationOptions.SYSTEM_DEFAULT_SOUND);
  // Vibrate using default system vibration motion when notification triggers
  options.setVibration(
             MafNativeLocalNotificationOptions.SYSTEM_DEFAULT_VIBRATION);

  // Add custom payload that is to be delivered through the local notification
  HashMap<String,Object> payload = new HashMap<String, Object>();

  payload.put("somenumber", 1);
  payload.put("somestring", "value2");
  payload.put("someboolean", true);
  options.setPayload(payload);

  // Schedule local notification
  String notificationID = AdfmfContainerUtilities.
                          addLocalNotification(options); 
  System.out.println("Notification added successfully. ID is "+notificationID);
}
catch(Exception e) {
  System.err.println("There was a problem adding notification");
}

    The notification options' impact on the behavior of your application depends on your target platform. For more information, see Section 24.3.5, "What You May Need to Know About Local Notification Options and the Application Behavior."

  • cancelLocalNotification(String notificationId). This method returns a String that represents the ID of the successfully canceled notification.

    In your Java code, you use this method in a manner similar to the following:

    try {
  String cancelledNotificationId = AdfmfContainerUtilities.
         cancelLocalNotification("a83b696d-53e7-4242-ab4d-4a771d8d178f");
  System.out.println("Notification successfully canceled"); 
}
catch(AdfException e) {
  System.err.println("There was a problem canceling notification");
}

For more information, see Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

24.3.2 How to Manage Local Notifications Using JavaScript

MAF allows you to manage local notifications using JavaScript APIs in the adf.mf.api.localnotification namespace. The following methods are available:

  • add, defined as follows:

    /**
* Schedule a local notification
*
* @param {Object} options - notification options
* @param {string} options.title - notification title
* @param {string} options.alert - notification alert
* @param {Date} options.date - date at which notification is to be triggered
* @param {Number} options.badge - application icon is to be badged by this 
*                                 number when notification is triggered
* @param {string} options.sound - set it to 'SYSTEM_DEFAULT' to play the
*                                 default system sound upon a notification
* @param {string} options.vibration - set it to 'SYSTEM_DEFAULT' for default 
*                                     system vibration upon a notification
* @param {Object} options.payload - custom payload to be sent via notification
* @param {successCallback} scb - success callback
* @param {errorCallback} ecb - error callback
*/
adf.mf.api.localnotification.add(options,scb,ecb);

{Object} options : json representing notification options
        {
           // notification title (only Android and iOS 8.2 or later)
           "title" : String,  
           // notification alert text
           "alert" : String,  
           // date-time at which notification should be fired (UTC time zone) 
           "date" : Date,  
           // either 'minutely', 'hourly', 'daily',
           // 'weekly', 'monthly', or 'yearly'
           "repeat" : String,  
           // badge application icon with this number (iOS only)
           "badge" : Number,  
           // if set, the default system sound is played
           "sound" : "SYSTEM_DEFAULT",  
           // if set to "SYSTEM_DEFAULT", the default vibration is 
           // enabled upon an incoming notification (Android only)
           "vibration" : String,  
           // custom JSON data to be passed through the notification
           "payload" : Object,  
        }


    /**
* Success Callback
*
* @param {Object} request - request
* @param {Object} response - response
* @param {string} response.id - id of the scheduled notification
*/
function scb(request, response) {}


    /**
* Error Callback
*
* @param {Object} request - request
* @param {Object} response - response
*/
 function fcb(request, response) {}

    The notification options' impact on the behavior of your application depends on your target platform. For more information, see Section 24.3.5, "What You May Need to Know About Local Notification Options and the Application Behavior."

  • cancel, defined as follows:

    /**
* Cancel a scheduled local notification
*
* @param {string} notificationId - id of the scheduled notification 
*                                  that needs to be canceled
* @param {successCallback} scb - success callback
* @param {errorCallback} ecb - error callback 
*/
adf.mf.api.localnotification.cancel(notificationId, scb, ecb);

{var} notificationId : id of notification that is to be canceled.


    /**
* Success Callback
*
* @callback successCallback
* @param {Object} request - request
* @param {Object} response - response
* @param {string} response.id - id of the notification
*/


    /**
* Error Callback
*
* @callback errorCallback
* @param {Object} request - request
* @param {Object} response - response
*/

    For more information, see Oracle Fusion Middleware JSDoc Reference for Oracle Mobile Application Framework.

24.3.3 How to Manage Local Notifications Using the DeviceFeatures Data Control

You can schedule and cancel a local notification using the addLocalNotification and cancelLocalNotification methods of the DeviceFeatures data control shown in Figure 24-3.

Figure 24-3 Methods of DeviceFeatures Data Control

This image is described in the surrounding text

For information about the DeviceFeatures data control, see Section 14.11, "Using the DeviceFeatures Data Control."

24.3.4 How to Handle Local Notifications

To enable handling of local notifications, MAF provides the following:

  • The EventListener interface that you must implement to create a listener for local notification events. When a notification is triggered, the onMessage method is called with the notification details:

    NativeLocalNotificationListener implements EventListener {
   @Override
   public void onOpen(String id) {
   }

   @Override
   public void onMessage(Event event) {
         //Application state at the time of this notification
         int appState = event.getApplicationState();

         //Get local notification event details
         if (event instanceof NativeLocalNotificationEvent) {
         NativeLocalNotificationEvent localNotificationEvent =
                                   (NativeLocalNotificationEvent) event;
         HashMap<String, Object> notification =
                                   localNotificationEvent.getPayloadObject();

         // do something with the notification payload, such as navigate
         // to an application feature, call a web service, and so on
   }

   @Override
   public void onError(AdfException error) {
   }
}

  • The NativeLocalNotificationEvent class that extends the oracle.adfmf.framework.event.Event.

To receive events related to local notifications, you need to add your listener in the registered ApplicationLifeCycleEventListener#start method as follows:

EventSource evtSource = EventSourceFactory.getEventSource(
            EventSourceFactory.NATIVE_LOCAL_NOTIFICATION_EVENT_SOURCE_NAME);
evtSource.addListener(new NativeLocalNotificationListener());

For more information, see Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

24.3.5 What You May Need to Know About Local Notification Options and the Application Behavior

Table 24-2 lists the local notification options and describes how setting certain values or failing to set values for each option affects the notification behavior of a MAF application.

Table 24-2 Local Notification Options

Option Value Behavior on iOS Behavior on Android

title

Either:

  • null

  • not specified

NA Foot 1 

The notification title in the notification center appears blank.

alert

Either:

  • null

  • not specified

If the notification has other properties specified, such as badge or sound, the notification is delivered to the operating system so that it plays a sound or updates the application icon badge, but the notification is not displayed in the notification center.

If the application is running in the foreground at the time of the notification delivery, the notification is delivered to the application's local notification listener.

The notification is displayed as a banner with a title but without the alert text.

date

Either:

  • null

  • not specified

  • time or date in the past

The notification is triggered immediately.

The notification is triggered immediately.

repeat

Either:

  • null

  • not specified

The notification does not repeat.

The notification does not repeat.

badge

Either:

  • null

  • not specified

  • negative number

The notification does not badge the application icon.

Any existing badge is maintained.

NA Foot 2 

badge

0

Any existing badge is removed from the application icon.

NA Foot 3 

sound

Other than SYSTEM_DEFAULT_SOUND

An error message is displayed.

The notification does not play sound.

An error message is displayed.

The notification does not play sound.

sound

Not specified

The notification does not play sound.

The notification does not play sound.

vibration

Other than SYSTEM_DEFAULT_VIBRATION

NA Foot 4 

An error message is displayed.

The notification does not trigger vibration of a mobile device.

vibration

Not specified

NA Foot 5 

The notification does not trigger vibration of a mobile device.

Footnote 1 The notification is not affected because its title is always the application name.

Footnote 2 There is no concept of application badging. The setting is ignored.

Footnote 3 There is no concept of application badging. The setting is ignored.

Footnote 4 You cannot control vibration. The setting is ignored. However, if you specify that the default system sound should be played upon receipt of a notification and if the end user enables the Vibrate on Ring setting on the mobile device, then the device will also vibrate when the notification is received.

Footnote 5 You cannot control vibration. The setting is ignored. However, if you specify that the default system sound should be played upon receipt of a notification and if the end user enables the Vibrate on Ring setting on the mobile device, then the device will also vibrate when the notification is received.