registerForRemoteNotifications

This front call registers a mobile device for push notifications.

Syntax

ui.Interface.frontCall("mobile","registerForRemoteNotifications",
   [sender_id], [registration_token] )

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.
registration_token - Registration token to be sent to the push notification provider. For GMA/Android, this is the "registration token" obtained from GCM, for GMI/iOS, this is the "device token" obtained from APNs.

Usage

The "registerForRemoteNotifications" front call registers the mobile device for push notifications. Once the registration procedure is done (see below for platform specifics), it is possible to get notification events through the notificationpushed predefined action, and retrieve notification data with the getRemoteNotifications front call.

Note: The app does not need to register for notification each time it is restarted: Even if the app is closed, the registration is still active until the unregisterFromRemoteNotifications front call is performed. At first execution, an app will typically ask if the user wants to get push notifications and register to the push service if needed. To disable push notification, apps usually implement an option that can be disabled (to unregister) and re-enabled (to register again) by the user. On Android, that the app must register for notification each time it is upgraded.

On Android when using GCM, you get the sender_id and an API key when you create a GCM project (see https://developers.google.com/cloud-messaging/android/client#get-config). The registration_token is the registration token returned by GCM. Once registered with the GCM service, the app must also send this registration token to the GCM application server. Registration tokens are typically sent to the GCM application server using a RESTFul HTTP POST. For more details, see GCM documentation on the Google developer web site. For more details about GCM registration, see About GCM Connection Server.

Note: Android apps using push notification services need specific permissions to be defined in the manifest, such as android.permission.GET_ACCOUNTS, com.google.android.c2dm.permission.RECEIVE, and especially application-package-name.permission.C2D_MESSAGE. These Android permissions will be automatically set by the gmabuildtool, according to the package name specified with the --build-app-package-name option. For more details, see GCM documentation.

On iOS when using APNs, the sender_id is ignored. The registration_token is the device token returned by the Apple Push Notification service. Once registered with the Apple Push Notification service, the app must also send this device token to the push notification provider, typically using a RESTFul HTTP POST.

For more details about Apple Push Notification Provider, see Apple Push Notification Service web site.

Example

The following code example registers with Google Cloud Messaging or Apple Push Notification service. It then sends the registration token to the push notification provider:

IMPORT com  -- For RESTful post
IMPORT util -- JSON API

CONSTANT GCM_SENDER_ID = "<enter your GCM Sender ID (NULL for APNs)>"
...

DEFINE sender_id STRING,
       registration_token STRING
DEFINE req com.HTTPRequest,
       obj util.JSONObject,
       resp com.HTTPResponse

-- First get the registration token
LET sender_id = GCM_SENDER_ID
CALL ui.Interface.frontCall(
        "mobile", "registerForRemoteNotifications", 
        [ sender_id ], [ registration_token ] )

-- Then send registration token to push notification provider
TRY
    LET req = com.HTTPRequest.create("http://SERVER_IP:4930")
    CALL req.setHeader("Content-Type", "application/json")
    CALL req.setMethod("POST")
    CALL req.setTimeOut(5)
    LET obj = util.JSONObject.create()
    CALL obj.put("registration_token", registration_token)
    CALL req.doTextRequest(obj.toString())
    LET resp = req.getResponse()
    IF resp.getStatusCode() != 200 THEN
       MESSAGE SFMT("HTTP Error (%1) %2",
                    resp.getStatusCode(),
                    resp.getStatusDescription())
    ELSE
       MESSAGE "Registration token sent."
    END IF
CATCH
    MESSAGE SFMT("Could not post registration token to server: %1", STATUS)
END TRY
...