- Obtaining a device token
- Using the Titanium PushNotifications API
- Parsing a notification payload
- More examples
Obtaining a device token
To receive push notifications, your application first needs to obtain a device token. To obtain a device token:
- On Android, call the CloudPush module's
- On iOS, call the
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:
- In Studio, open your project's
- In the Modules section, click the add (+) button.
- Select ti.cloudpush and click OK.
In your application code, require the
ti.cloudpush module and call its
method, and register event handlers to respond to
error events. Once a device token has been retrieved, your application can listen for the
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
and setup callbacks for the
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_ALERT, NOTIFICATION_TYPE_BADGE, NOTIFICATION_TYPE_NEWSSTAND , or NOTIFICATION_TYPE_SOUND.
You need to register the user notification types you want to use with the
method before calling the
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
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
unsubscribeToken()) and sending notifications
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:
- Open your project's
- In the Modules section, click the Add button (green plus sign).
- Select ti.cloud 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
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
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
To obtain the device's current location, you call the
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:
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
Sample payload sent push notification in the multiline format on an Android device:
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
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).