Ti.CloudPush Module

Description

Push notifications for Android via Appcelerator Cloud Services. When push is enabled, this module persistently connects to the ACS servers using a long lived and very light TCP socket. Using this, push notifications can be sent to your users.

For more information, please look at the Appcelerator Cloud Services documentation on http://www.appcelerator.com/.

Getting Started

View the Using Titanium Modules document for instructions on getting started with using this module in your application.

Accessing the Ti.CloudPush Module

To access this module from JavaScript, you would do the following:

var CloudPush = require('ti.cloudpush');

Methods

number isGooglePlayServicesAvailable()

Returns a number value indicating the availability of Google Play Services which are for push notifications.

Possible values include SUCCESS, SERVICE_MISSING, SERVICE_VERSION_UPDATE_REQUIRED, SERVICE_DISABLED, and SERVICE_INVALID.

void retrieveDeviceToken(Dictionary args)

Asynchronously retrieves the device token that you should use for any calls to the Appcelerator Cloud Service's subscribe or unsubscribe to push notification channels. This token is unique to each application, and each device.

Takes a single argument, an object literal with the following required properties:

void clearStatus()

A method to clear stored Push status including Push type, device token, GCM SenderId, etc. This method is useful for changing GCM SenderId when needed. After calling this app, Push will be reinitialized, and please start to get device token again.

Properties

WARNING: The defaults listed below are used until you set a property for the first time. Because the properties are persisted to the device settings (just like Ti.App.Properties), the most recent value you set will always be used.

boolean showTrayNotification [defaults to true]

Whether or not to show a tray notification when a new push is received. If your payload is only a string, it will be used as the contentText and tickerText, and your application's name will be used as the contentTitle with a system icon.

icon

Icons that are to be referenced by push notifications sent to the application should be placed in the 'platform/android/res/drawable' folder of the application. Icon file names are specified in the notification message without their file extension (e.g. 'logo').

sound

Sound files that are to be played by push notifications sent to the application should be placed in the 'Resources/android/sound' folder of the application. Sound file names are specified in the notification message with their file extension (e.g. 'mysound.mp3').

boolean showAppOnTrayClick [defaults to true]

Whether or not clicking the tray notification will bring your application to the foreground. This is only applicable if you have set "showTrayNotification" to true.

boolean showTrayNotificationsWhenFocused [defaults to false]

Whether or not to show tray notifications when your application is in the foreground.

boolean focusAppOnPush [defaults to false]

Whether or not your application is brought to the foreground whenever a new push is received.

Constants

number SUCCESS

Returned by isGooglePlayServicesAvailable if the connection to Google Play services was successful.

number SERVICE_MISSING

Returned by isGooglePlayServicesAvailable if Google Play services is missing on this device.

number SERVICE_VERSION_UPDATE_REQUIRED

Returned by isGooglePlayServicesAvailable if the installed version of Google Play services is out of date.

number SERVICE_DISABLED

Returned by isGooglePlayServicesAvailable if the installed version of Google Play services has been disabled on this device.

number SERVICE_INVALID

Returned by isGooglePlayServicesAvailable if the version of the Google Play services installed on this device is not authentic.

Events

trayClickLaunchedApp

Fired when a tray notification is shown and the application is not running. Touching it launches the app, and fires this event.

This event receives an object literal with a single property:

trayClickFocusedApp

Fired when a tray notification is shown and the application is already running. Touching it focuses the app, and fires this event.

This event receives an object literal with a single property:

callback

Fired whenever a push notification is received. If your application is not running when a push is received, the push will be saved in a queue until the next time you add an event listener for this.

This event receives an object literal with a single property:

Example listener:

    CloudPush.addEventListener('callback', function (evt) {
        Ti.API.info('Received push! ' + evt.payload);
        Ti.API.info('JSON: ' + JSON.parse(evt.payload));
        alert(evt.payload);
    });

TiApp.xml

The constants this module uses can be overriden in your tiapp.xml, as follows:

acs-push-api-url, acs-push-api-url-production, acs-push-api-url-development

Specifies which ACS api url is used.

acs-gcm-sender-id, acs-gcm-sender-id-production, acs-gcm-sender-id-development

Specifies the required GCM sender id. If you visit https://code.google.com/apis/console, and create an app (or use an existing one), the sender ID will be in your URL following "#project:". For example, it may look like "801234118521".

acs-grouped-notification-message, acs-grouped-notification-message-production, acs-grouped-notification-message-development

Specifies grouped message when there are more than one unread messages in Android notification tray. Use "$number$" to represent number of unread message. For example, if setting acs-grouped-notification-message to "You have $number$ unread messages.", you will get "You have 3 unread messages." if there are 3 unread message. This value also can be set by acs_grouped_notification_message under i18n/specific_locale/string.xml, to have an internationalization support.

Usage

See example.js

Author

Dawson Toth, Jeff English, Paul Lv and Jon Alter

Module History

View the change log for this module.

Feedback and Support

Please direct all questions, feedback, and concerns to info@appcelerator.com.

License

Copyright(c) 2012-2014 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE file included in the distribution for further details.