Initializing and Registering a Device

Initializing and Registering a Device

You need to register each device that you want to send push notifications to. The register operation takes care of two tasks:

  • Registers (initializes) the device with its vendor's push notification service—This step includes acquiring a push notification token from the vendor's push notifications service that authorizes Telerik Platform to send messages to the device.
  • Creates a device registration in Telerik Platform—This step includes saving the device's push notification token along with other details in Telerik Platform.

A device registration describes a single device that has been registered for push notifications in your Telerik Platform application. The object that represents the registration contains required system properties such as token, device model, operating system type, time zone, etc. as well as custom parameters that you have added during registration.

Later, when you send notifications to devices that run your app, you can use both the system and the custom parameters to precisely target who receives what.

This article is organized as follows:

Initializing and Registering a Device

The Backend Services JavaScript SDK combines the initialization and registration steps into a single function call. If the device is already registered with Telerik Platform, calling the register() function will only update the registration parameters.

The following code both initializes the device for push notifications and registers it with Telerik Platform. The full list of settings that you can use is described in Table of Registration Settings.

var el = new Everlive('your-app-id');
var pushSettings = {
    iOS: {
        badge: true,
        sound: true,
        alert: true,
        clearBadge: true
    },
    android: {
        senderID: 'SENDER_ID_HERE'
    },
    wp8: {
        channelName: 'EverlivePushChannel'
    },
    notificationCallbackIOS: function(e) {
        // logic for handling push in iOS
    },
    notificationCallbackAndroid: function(e) {
        // logic for handling push in Android
    },
    notificationCallbackWP8: function(e) {
        // logic for handling push in Windows Phone. Not available in NativeScript.
    },
    customParameters: {
        myParameter1: "MyValue1",
        myParameter2: "MyValue2"
    }
};

el.push.register(
    pushSettings,
    function successCallback(data) {
        // This function will be called once the device is successfully registered
    },
    function errorCallback(error) {
        // This callback will be called any errors occurred during the device
        // registration process
    }
);

The device can receive push notifications immediately after register() completes successfully. The registration process produces a device registration object that you can get for the current device using getRegistration(). The registration object contains the device's unique HardwareId, among other data. You can also see the device details in the Telerik Platform portal under Notifications > Push Notifications > Devices.

The function registers the device with a dummy token when called while the app is running in the Telerik AppBuilder emulator/simulator. This allows the method to succeed, but doesn't mean that you can send push notifications to the emulator/simulator.

The push token is automatically stored in Telerik Platform. If you still need to access it, you can do so in the successCallback where it is received as an object containing the push token (token).

On iOS devices the initialization step causes the operating system to ask the user if they want to receive push notifications from your app when the app is ran for the first time.

Table of Registration Settings

Because the Backend Services JavaScript SDK initializes and registers the device in a single SDK operation, you need to provide both initialization and registration settings.

The full list of settings is presented in the next table. With the exception of customParameters which sets custom parameters that are kept in Telerik Platform, all settings relate to initialization and are not saved in Telerik Platform. The resulting registration object that is stored in Telerik Platform is described in Table of Registration Object Fields.

Field Name Field Type Description
iOS.alert bool Set to true to enable the device to display alerts.
iOS.badge bool Set to true to enable the device to display notification badges on the app icon.
iOS.sound bool Set to true to enable the device to play notification sounds.
iOS.clearBadge bool Set to true to reset the badge count back to 0.
android.senderID string This is the Sender ID key of your Firebase project (formerly the Google API project number). It is required when obtaining a push token for an Android device.
android.projectNumber string Synonym for android.senderID. Available in Backend Services JavaScript SDK versions 1.2.7 and later.
wp8.channelName string This is the name of the push channel the device is registering to. Not available in NativeScript.
notificationCallbackIOS function Specifies a custom callback to be used when a push notification is received on iOS.
notificationCallbackAndroid function Specifies a custom callback to be used when a push notification is received on Android.
notificationCallbackWP8 function Specifies a custom callback to be used when a push notification is received in Windows Phone 8. Not available in NativeScript.
customParameters object An object containing custom parameters to be included in the device registration.

Handling Errors

In case of an error the errorCallback will be invoked with a single error argument. The error argument has the following format:

{
    errorType: <number>,
    message: <string>,
    additionalInformation: {
        // optional information including the original error
    }
}

The errorType parameter can take these values:

  • 1 indicates that an error has occurred with the native push plugin
  • 2 indicates that an error occurred while making a call to Telerik Platform

The message parameter contains a textual error message returned by the native push plugin or Telerik Platform depending on the errorType value.

iOS: Interactive Notifications

iOS 8.0 introduced interactive notifications. Interactive notifications allow you to specify notification buttons and actions to be displayed on a push notification received when your application is in the background. iOS 9.0 adds text input to interactive notifications.

To send interactive notifications you need to first set up a category when registering the device. A category is a set of actions that are offered to the user. Your application is notified of the action that the user selected.

Later, when you send a push notification to the device, you have to set the "category" field to a valid category identifier. This will make the OS automatically add the predefined actions to the push notification.

The next example registers a device with interactive notification settings. They are added to the interactiveSettings object inside the iOS settings object and define a category named READ_CATEGORY containing two action buttons—Read and Cancel. The register method automatically modifies the device's user notification settings accordingly.

 var pushSettings = {
     iOS: {
         badge: "true",
         sound: "true",
         alert: "true",
         interactiveSettings: {
             actions: [{
                 identifier: 'READ_IDENTIFIER',
                 title: 'Read',
                 activationMode: window.plugins.pushNotification.UserNotificationActivationMode.Foreground,
                 destructive: false,
                 authenticationRequired: true
             }, {
                 identifier: 'CANCEL_IDENTIFIER',
                 title: 'Cancel',
                 activationMode: window.plugins.pushNotification.UserNotificationActivationMode.Foreground,
                 destructive: false,
                 authenticationRequired: true
             }],
             categories: [{
                 identifier: 'READ_CATEGORY',
                 actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'],
                 actionsForMinimalContext: ['READ_IDENTIFIER']
             }]
         },
         notificationCallbackIOS: onIosPushReceived
     }
 };

The onIosPushReceived callback is passed a category field containing the category identifier and an identifier field containing the id of the action selected by the user. You can wire up your custom application functionality based on these fields.

Table of IOS Interactive Notifications Registration Fields

The full list of fields that you can use to set up interactive notifications is presented in the next table.

Field Name Field Type Default Value Description
interactiveSettings.actions Array null An array that holds all category actions.
interactiveSettings.actions[index].identifier string null A unique identifier for the action specified by index.
interactiveSettings.actions[index].title string null A label for the action specified by index. It is displayed as a button on the notification.
interactiveSettings.actions[index].activationMode string background A mode for the action specified by index. Value "foreground" starts the application on button press; value "background" performs a background task only.
interactiveSettings.actions[index].destructive bool false Set to true if the action is potentially destructive to the user's data or application. The system hints this by displaying the corresponding button in a contrasting way—commonly in red.
interactiveSettings.actions[index].authenticationRequired bool false If set to true, the user must unlock the phone before the action is performed.
interactiveSettings.actions[index].behavior string null (iOS 9 only) Set to window.plugins.pushNotification.ActionBehavior.TextInput to draw a text input field.
interactiveSettings.categories Array null An array that holds all categories to be registered in the device's user notification settings.
interactiveSettings.categories[index].identifier string null (Required) A unique identifier for the category specified by index.
interactiveSettings.categories[index].actionsForDefaultContext Array null (Required) An array of actions displayed when the notification has an alert UI.
interactiveSettings.categories[index].actionsForDefaultContext Array null (Required) An array of actions shown when the notifications has a banner UI or is shown on the lock screen.

iOS: Controlling the Device Badge Count

You might want to change the badge count when the application launches or the user navigates to a specific screen.

This is how to clear both the badge count on the device and the corresponding value stored on the server:

    el.push.clearBadgeNumber(function onSuccess () {
        alert('Badge cleared');
    }, function onError (error) {
        alert(JSON.stringify(error));
    });

If, instead, you want to set the badge to a specific number (again, both on the device and the server) you can use code similar to the following:

    var badgeNumber = 5;
    el.push.setBadgeNumber(badgeNumber,
        function onSuccess () {
            alert('Badge set');
        },
        function onError (error) {
            alert(JSON.stringify(error));
        });

See Also


Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.