ACS Push Notification using GCM

Titanium CloudPush module supports two protocols for send push notifications to Android devices.

1. GCM (Google Cloud Messaging) 
   From Ti SDK 3.1.2 onwards, GCM is the default method to send push notifications. GCM supports devices that run Android 2.2 and later, and requires that the Google Play Store application be installed. For pre-4.0 devices, the user is required to set up their Google account. 
   
   If you have an existing application that uses the MQTT protocol, you either need to transition your application to use GCM or set the acs-push-type key in the tiapp.xml file to mqtt. This will be explain in detail at end of this tutorial.


2. MQTT (MQ Telemetry Transport) 
   It is lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. It consumes less battery. MQTT does not have any specific device requirements.

Here I am going to explain ACS Push Notification using GCM and migrating existing MQTT protocol application to GCM.

We can achieve GCM Push Notification in 6 easy steps

1. Setting up Google Cloud Messaging
2. Push Configuration in ACS Console
3. CloudPush Module Implementation
4. Retrieve Device Token
5. Cloud User Login
6. Subscribe a Channel

1.  Setting up Google Cloud Messaging

Following information taken from here.

To use GCM, you need to create a Google API project to obtain a Google API key and GCM sender ID. For instructions on creating and obtaining these items, see Android Developer: Getting Started with GCM and follow the directions in "Creating a Google API Project", "Enabling the GCM Service" and "Obtaining an API Key".

When creating a new server key, you are asked for a list of IP addresses to accept requests from. Do not enter any information in the textbox and click Create to accept all IP addresses.

Now you will have Google Cloud Messaging (GCM) API Key and GCM sender ID. We are going to used these two values in Step 2.

For detailed instructions, see the "Push Notification" section of ACS: Android SDK.

Google Cloud Messaging Console

2. Push Configuration in ACS Console

Go to https://my.appcelerator.com/apps, then go to My Apps -> Manage ACS -> DEVELOPMENT -> Settings/Android Push Configuration and enter your Google API key in the Google Cloud Messaging (GCM) API Key textbox and GCM sender ID in the Google Cloud Messaging (GCM) Sender ID textbox. (which we got from Step 1) 

Android Push Configuration

Note: If you are using MQTT, just enter application package alone.

3. CloudPush Module Implementation

• Add CloudPush module into your application.
• To use push notifications, in the tiapp.xml file, you need to specify push type (either gcm or mqtt). 

CloudPush module

4. Retrieve Device Token

Call the retrieveDeviceToken method before setting the enabled property to true to enable the device to receive push notifications. You must call retrieveDeviceToken before any other CloudPush API call or else the device will not receive push notifications. So below code must be top of any other CloudPush API call.

var CloudPush = require('ti.cloudpush');
CloudPush.retrieveDeviceToken({
    success: function deviceTokenSuccess(e) {
        Ti.API.info('Device Token: ' + e.deviceToken);
    },
    error: function deviceTokenError(e) {
        alert('Failed to register for push! ' + e.error);
    }
});

5. Cloud User Login

Before subscribe for Push Notification, cloud user should logg in.  So create a test user in Appcelerator Cloud Console My Apps -> Manage ACS ->  DEVELOPMENT ->  Users
and login with credential. Use below code for cloud user login

Cloud.Users.login({
    login: 'push123',
    password: 'push123'
}, function (e) {
    if (e.success) {
        alert("login success");
    } else {
        alert('Error: ' + ((e.error & amp; & amp; e.message) || JSON.stringify(e)));
    }
});    

6. Subscribe a Channel

Add following code for channel subscription

 
Cloud.PushNotifications.subscribe({
    channel: 'alert', //'alert' is channel name
    device_token: deviceToken,
    type: 'gcm' //here i am using gcm, it is recommended one
}, function (e) {
    if (e.success) {
        alert('Subscribed for Push Notification!');
    } else {
        alert('Subscribe error:' + ((e.error & amp; & amp; e.message) || JSON.stringify(e)));
    }
});

Using MQTT with ACS

Using MQTT with ACS similar to above one, but few steps has slighter difference. Please follow below things

1. Step 1(Setting up Google Cloud Messaging) not necessary 
2. In Step 2, just enter application package in text box. No need to enter GCM API Key and GCM sender ID
3. In Step 3, use acs push type as mqtt instead of gcm
4. In Step 6, use type as 'android' instead of 'gcm'

Cool.., You have completed Android Push Notification setup(Here is the whole sample app). This is time for testing, run the application in android device and click the button "Android Cloud Push Notification". You will get 3 alerts continuously.

Then go to My Apps -> Manage ACS -> DEVELOPMENT -> Push Notifications, here you can see "1 Android clients subscribed to push notifications"

Push Notifications Subscription

How to customize ACS Push notification?
Here you can use use your custom sounds and icons.

Icon
custom icons must be placed in below directory
app_root/platform/android/res/drawable/myicon.png 

Here "myicon.png" is custom icon, specified in the push message without the filename extension. For example: in icon text box enter the file name without extension(myicon)

Sound
Custom sound must be placed in below directory
app_root/platform/android/assets/sound/beep.wav 

Here "beep.wav" is custom sound, specified in the push message with the filename extension. For example: in custom sound text box you have to enter sound filename with extension(beep.wav). Here is the screens of custom notification

ACS Push Notification Screenshot

Source code:
 
Here you can download the complete working project from my Github ACS Android Push Notification with GCM

Note: 

1. AppC strongly recommend you to use and migrate to GCM.
2. java.lang.ExceptionInInitializerError at com.appcelerator.cloud.push.CCPushService.registerGCMServiceBackground(CCPushService.java:482) - If you encountered this error in Android 2.3, you have to use ti.cloudpush 2.3.3. You can download here.

References:

• http://docs.appcelerator.com/platform/latest/#!/api/Titanium.CloudPush
• http://docs.appcelerator.com/platform/latest/#!/api/Titanium.Cloud.PushNotifications
• http://docs.appcelerator.com/cloud/latest/#!/guide/android
• http://developer.appcelerator.com/blog/2013/08/android-push-notification-deprecating-mqtt-in-favor-of-gcm.html
• https://developer.appcelerator.com/question/157032/cloudpushretrievedevicetoken-error