registerForRemoteNotifications

This front call registers a mobile device for push notifications.

Syntax

ui.Interface.frontCall("mobile","registerForRemoteNotifications",
   [], [registration-token] )

registration-token - Registration token to be sent to the push notification provider. For GMA/Android, this is the "registration token" obtained from Firebase Cloud Messaging (FCM), for GMI/iOS, this is the "device token" obtained from Apple Push Notification services (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™, the app must register for notification each time it is upgraded.

Registering with FCM on Android

On Android the registration-token is the registration token returned by FCM. Once registered with the FCM service, the app must also send this registration token to the FCM application server. Registration tokens are typically sent to the FCM application server using a RESTFul HTTP POST.

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, depending on the package name specified with the --build-app-package-name option.

For more details, see FCM documentation and About FCM Connection Server.

Registering with APNs on iOS

On iOS when using APNs, 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 the Apple Push Notification Service web site.

Example

The following code example registers with Firebase 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

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

-- First get the registration token
CALL ui.Interface.frontCall(
        "mobile", "registerForRemoteNotifications", 
        [ ], [ 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
...