Skip to end of metadata
Go to start of metadata
For a push notification to reach a user, the user (or device) must be subscribed to receive push notifications on one or more notification channels. The application must also obtain a device token, which permits Mobile Backend Services (MBS) to communicate with the push service provider (Google Cloud Messaging (GCM), Firebase Cloud Messaging (FCM), or Apple Push Notification). Firebase Cloud Messaging (FCM) is the new version of GCM. This guide explains how to how obtain a device token, and how to use the PushNotifications API to manage your user's notification subscriptions.

Obtaining a device token

To receive push notifications, your application first needs to obtain a device token. To obtain a device token:

Once your application has obtained a device token it should save it for later use.

Obtaining a device token on Android

To obtain a device token from GCM or FCM, you first need to add the CloudPush module to your project. This module is included with the Titanium SDK, but is not included by default in new projects.

To add the CloudPush module to your project:

  1. In Studio, open your project's tiapp.xml file.
  2. In the Modules section, click the add (+) button.
  3. Select ti.cloudpush and click OK.

In your application code, require the ti.cloudpush module and call its  retrieveDeviceToken()  method, and register event handlers to respond to success and error events. Once a device token has been retrieved, your application can listen for the  callback  event to process incoming push notifications. Your application should save the device token for later use. The following code demonstrates the minimal code required to obtain a device token and setup event handlers:

Obtaining a device token on iOS

To obtain a device token on iOS, call the Titanium.Network.registerForPushNotifications() and setup callbacks for the success, error, and callback events. You can also specify the types of notifications enabled for your application, which can include one or more of the following:  NOTIFICATION_TYPE_ALERTNOTIFICATION_TYPE_BADGENOTIFICATION_TYPE_NEWSSTAND , or  NOTIFICATION_TYPE_SOUND.

You need to register the user notification types you want to use with the Titanium.App.iOS.registerUserNotificationSettings() method before calling the registerForPushNotifications() method.

Using the Titanium PushNotifications API

Once your application has obtained a device token and setup callback event handlers, you can use the Modules.Cloud.PushNotifications APIs to manage the user's notification subscriptions. You use the PushNotifications API to subscribe and unsubscribe to notifications channels, send notifications to other MBS users or devices, or query MBS for the current user's subscriptions. 

Session- and token-based subscriptions

Arrow Push provides two ways for an application to manage its push notification subscriptions: session-based and token-based.  Session-based subscriptions require that the current user be logged in to MBS to subscribe/unsubscribe, send, or receive push notifications. Token-based notifications only require the application to retrieve a device token (see Obtaining a device token ).

The Cloud.PushNotifications  API provides equivalent methods for using either of these approaches. For instance, you call the  subscribe() method to subscribe the currently logged in API Builder Push user to a channel, or subscribeToken() to subscribe an application user with only the obtained token. Similarly, there are equivalent methods for unsubscribing from a channel (unsubscribe() and unsubscribeToken()) and sending notifications (notify() and notifyToken()).


It's recommended that you use either session- or token-based subscriptions in your application, but not both together.

Adding the Cloud module to your project

The Cloud module is included with the Titanium SDK, but is not enabled by default in new projects. 

To add the Cloud module to your project:

  1. Open your project's tiapp.xml file.
  2. In the Modules section, click the Add button (green plus sign).
  3. Select and click OK .

Subscribing to Push Notifications with Device Tokens

To subscribe your application to receive push notifications using only a device the token, you call the subscribeToken() method. In the following sample code,  the user is subscribed to the "news_alerts" channel when tap the Subscribe button; tapping the Unsubscribe button calls the  unsubscribeToken() method.

The following example is functionally identical to the token-based version, except that it includes functionality to log the user into MBS.  

Subscribing to Push Notifications with User Sessions

You can subscribe to receive push notifications based the user's current MBS session. If you do not require push notifications to be sent to specific users, then consider using token-based notifications .  You can create an MBS user in Appcelerator Dashboard or programmatically (as shown in the example for  Modules.Cloud.Users ). 

  The following example is identical to the token-based version, except that it includes functionality to log the user into API Builder.  

Updating Subscriptions with Device Location

AMPLIFY Appcelerator Services' users can send push notifications to devices located within a geographic area you specify (see Sending and Scheduling Push Notifications). For a geo-based push to reach its intended recipients, the application must periodically update its location with API Builder by calling the updateSubscription() method.

To obtain the device's current location, you call the  getCurrentPosition() or registering to listen for location events. Doing this frequently, however, can be a significant drain on the device's battery.

  The Ti.Geofence module (requires a Team or Enterprise subscription) provides a more battery-efficient way to monitor a device's movement in to, or out of, virtual geographic perimeters, or geofences

When the device enters a defined geofence region, the application is notified and can obtain the device's current location and send it to API Builder. The following code demonstrates this approach.

Parsing a notification payload

The notification payload that is delivered to the device is modified slightly structure is a bit different between Android and iOS, as shown below.

The original JSON payload:

iOS payload:

Android parsed payload:

For example, in the following example the receivePush() method was previously assigned to the notification callback handler. The following code parses the alert string from the notification payload, and assigns it to a variable named alertString

Sample payload sent push notification in the multiline format on an Android device:

More examples

For another demonstration of the PushNotification API, run the Cloud demo app and select Push Notifications. The code for the Cloud demo is located in the Cloud module at <PATH_TO_TITANIUM_SDK>/modules/commonjs/<VERSION>/example/.


Unable to retrieve a device token (iOS)

Error: APSCloudPush has not been enabled. Call APSCloud.enable(context, key) to enable. (Android)

If LiveView is enabed, disable it.  There are some known conflict when using LiveView and push notification services (TIMOB-19233).

  • No labels