getRemoteNotifications
This front call retrieves push notification messages.
Syntax
ui.Interface.frontCall("mobile","getRemoteNotifications",
[], [data] )
- 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.
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.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
then performs a getRemoteNotifications front call as in
the usual way, to get the pending notifications pushed to the device while the app was off.
- 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 agetRemoteNotifications
front call. Even if there is no data available with the front call, it is recommended that the app sends a request directly to the server push provider to get last push data. - If the push notification does not contain badge numbers, it is still recommended that the app
performs a
getRemoteNotification
front call when it starts. If there is no push data available from the front call, the recommendation is that the app sends a request to the server push provider to see if there is push data available. This is by the way also recommended when receiving anotificationpushed
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. It is recommended that the app perform agetRemoteNotifications
front call and get the push data.
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.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 FCM 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 FCM application message, and thedata
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, that is required to be re-sent to the push notification server.
- When
"from"
- Contains the FCM project id.
[
{
"type": "message",
"data": { custom-attributes ... },
"from": "project-id"
},
{
"type": "token",
"data": "new-registration-token",
"from": "project-id"
},
...
]
"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, thealert
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 allows the remote notification to act as a "silent" notification. The recommendation is that notifications received in background mode are 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
DEFINE notif_list STRING
DIALOG ...
...
ON ACTION notificationpushed
CALL ui.Interface.frontCall(
"mobile", "getRemoteNotifications",
[ ], [ notif_list ] )
-- Analyse content of notiflist
DISPLAY util.JSON.format(notif_list)
...