getRemoteNotifications

This front call retrieves push notification messages.

Syntax

ui.Interface.frontCall("mobile","getRemoteNotifications",
   [sender_id], [data] )

sender_id - For GMA, the sender_id identifies the mobile device. It's obtained when you create a GCM project. This parameter is ignored by GMI.
data - STRING containing a JSON array of notifications.

Usage

After registering for push notifications with the registerForRemoteNotifications front call, the getRemoteNotifications front call can be called in the context of an ON ACTION notificationpushed action handler.

The GMI or GMA front-end will send the notificationpushed special action, when it receives notifications from the push notification server. When this action is fired, use the getRemoteNotifications front call to get notification data. On GMA, identify the GCM client by passing the sender_id obtained from the GCM project as a parameter. On GMI, the sender_id can be NULL, as it is ignored.

Important:

When an app restarts, if notifications are pending and the app has already registered for push notification in a previous execution, the notificationpushed action will be raised as soon as a dialog with the corresponding ON ACTION handler activates. The app should then perform a getRemoteNotifications front call as in the regular case, to get the pending notifications pushed to the device while the app was off.

However, special consideration needs to be given to iOS devices. When push notification arrives for an iOS app that has not started, there is no mechanism to wake up the app and get the push data. Therefore, when the user starts the app from the springboard, there will never have any push data available. Depending on the context, implement the following programming patterns to solve this problem:

If the push notification contains a badge number, the app can verify if the badge is greater than 0 (with the getBadgeNumber front call) in order to perform a getRemoteNotifications front call. Even if there is no data available with the front call, the app should directly ask the server push provider to get last push data.
If the push notification does not contain badge numbers, the app should always perform a getRemoteNotification front call when it starts. If there is no push data available from the front call, the app should ask the server push provider if there is push data available. This is by the way also recommended when receiving a notificationpushed action during application life time.
If the user starts the app from the Notification Center, the app is launched with push data transmitted from the system, and the notificationpushed action is sent. The app should the perform, the getRemoteNotifications front call and get the push data.

The "getRemoteNotifications" front call returns a list of notification records as a JSON array string. Use the util.JSONArray or util.JSON class to extract notification data from the returned string. The structure of a push notification is platform specific. See below for details.

Important: When an iOS app is in background, silent push notifications can occur, but notification message data (i.e. the payload) may not be available. In such case, GMI is able to detect that a notification arrived (i.e. when the app badge number is greater than zero) and raise the notificationpushed action, but the getRemoteNotifications front call will return no message data (data return param is NULL). If such case, implement a fallback mechanism (based on RESTFul web services for example), to contact the push notification provider and retrieve the message information.

Push notification records with GMA / Android™

The returned JSON string from a GCM notification server contains an array of notification records.

A notification record contains the following JSON keys:

"type" - can be "message" or "token".
"data" - Contains notification data.
- When "type":"message", the notification record is a GCM application message, and the data attribute contains custom notification information.
  An element of "data" can be a "genero_notification" record, that will produce an Android graphical notification. This record must define the following attributes:
  - "title" - title of the graphical notification
  - "content" - text content of the graphical notification
  - "icon" - icon of the graphical notification
  The "genero_notification" record can be followed by custom notification data.
- When "type":"token"", the notification record is a registration token update, and the "data" attribute contains the new registration token, which should be re-sent to the push notification server.
"from" - Contains the GCM project id.

JSON push notification data example for GMA:

[
 {
  "type": "message",
  "data": { custom-attributes ... },
  "from": "project-id"
 },
 {
  "type": "token",
  "data": "new-registration-token",
  "from": "project-id"
 },
 ...
]

Note that the JSON push notification data can contain a "data" attribute with a "genero_notification" record, that will produce an Android graphical notification:

[
 {
  "type": "message",
  "data": { 
            "genero_notification" :
            {
             "title"   : "Game Request!",
             "content" : "Bob wants to play poker...",
             "icon"    : "smiley"
            },
            custom-attributes
            ...
          },
  "from": "project-id"
 },
 ...
]

Push notification records with GMI / iOS

The returned JSON string from an Apple Push Notification contains an array of notification records.

A push notification record contains the following JSON attributes:

"aps" (required) - key to be recognized by devices as an Apple Push Notification
- "alert" (required) - key of the push notification content. If not specified as a single value, the alert key can hold:
  - "title" - title of the alert.
  - "body" - the message to be displayed.
- "badge" (optional) - the number to display as the badge of the app icon. If this property is absent, the badge is not changed. You need to manage it through your push notification provider.
- "sound" (optional) - the sound played by the alert (aiff, wav, or caf format). default value : "default". To use a custom file you will need to use the gmi extension project and be familiar with Objective-C. The file must bundled with the app.
- "content-available" (required) - The content-available property with a value of 1 lets the remote notification act as a “silent” notification. Notifications received in background mode should be stored for delivery when the app enters foreground mode.

JSON push notification data example for GMI:

[
 {
  "aps" :
  {
    "alert" : "My first push",
    "badge" : 1,
    "sound" : "default",
    "content-available" : 1
  }
 },
 {
  "aps" :
  {
    "alert" :
    {
      "title" : "Push",
      "body" : "My second push"
    }
    "badge" : 2,
    "sound" : "default",
    "content-available" : 1
  },
  "new_ids" : [ "XV234", "ZF452", "RT563" ],
  "updated_ids" : [ "AC634", "HJ153" ]
 }
]

In the last record, custom information is provided in the "new_ids" and "updated_ids" attributes, as a JSON array of identifiers.

For more details, see Apple Push Notification Service.

Example

IMPORT util -- JSON API
CONSTANT GCM_SENDER_ID = "<enter your GCM Sender ID (NULL for APNs)>"
...
DEFINE notif_list STRING,
       sender_id STRING

LET sender_id = GCM_SENDER_ID

DIALOG ...
  ...
  ON ACTION notificationpushed

     CALL ui.Interface.frontCall(
             "mobile", "getRemoteNotifications", 
             [ sender_id ], [ notif_list ] )

     -- Analyse content of notiflist
     DISPLAY util.JSON.format(notif_list)
  ...