How To Develop Smart Android Notifications using Google Cloud Messaging Service

Transcription

1 Software Engineering Competence Center TUTORIAL How To Develop Smart Android Notifications using Google Cloud Messaging Service Ahmed Mohamed Gamaleldin Senior R&D Engineer-SECC Copyright Software Engineering Competence Center 2013

2 Abstract Google Cloud Messaging for Android (GCM) is a service that helps developers to send data from servers to their Android applications on Android devices. The service was unveiled on June 27, 2012, at Google I/O 2012 held at the Moscone Center in San Francisco [1]. The GCM service handles all aspects of queuing of messages and delivery to the target Android application running on the target device. It is completely free whatever your messaging needs are and it can be used in some applications like smart notification systems. This tutorial gives an overview about the Google GCM service and provides hands-on experience on using this technology in a case study for energy-aware smart home application developed at Software Engineering Competence Center (SECC). Keywords: Google Cloud Messaging (GCM), Cloud to Device Messaging (C2DM), Android smart notifications. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 2

3 Table of Contents 1. Introduction 4 2. Getting started with the GCM service 4 3. How the GCM works? GCM Lifecycle Example of Android Application that Uses the GCM Architecture of Android Application that uses GCM GCM process flow Enabling GCM Sending a message Receiving a message Application server App Android App Creating the Manifest file Android app structure Invoker Application Invoker example architecture Summary References Abbreviations 38 How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 3

4 1. Introduction Google Cloud Messaging for Android (GCM) is a service that allows you to send data from your server to the users' Android-powered device. This could be a lightweight message telling your app there is new data to be fetched from the server like new version of apps or something like that [1]. The GCM service handles all aspects of storing, queuing and delivery of messages to the target Android application running on the target device. It is a completely free service whatever your messaging needs are. Google Cloud Messaging technology is the new version of the C2DM (cloud to device messaging) technology as the C2DM service has been officially deprecated as of June 26, 2012 which means that C2DM has stopped accepting new users and quota requests. The GCM could be considered as a more efficient implementation of the C2DM technology. The GCM service has many characteristics as described in [2]: 1. It allows 3rd-party application servers to send messages to their Android applications. This is a key feature as you always need your server application to be in direct contact with the mobile application such that you can send messages to the mobile application about new versions for instance. 2. An Android application on an Android device doesn't need to be running to receive messages. The system will wake it up the Android application via Intent broadcast when the message arrives. This is achieved if the application is set up with the proper broadcast receiver and permissions in the AndroidManifest.xml file. 3. The application has full control of how to handle the GCM messages passed to it. For example, the application might post a notification when receiving these messages. 4. It requires devices running Android 2.2 or higher that also have the Google Play Store application installed. 2. Getting started with the GCM service To start writing an Android application and the server-side application using the client and server helper libraries provided by GCM, you must begin with the first How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 4

5 step which is creating a Google API project. The following steps explain how the Google API project is created [1]: 1. Open the Google API console page 2. If you haven't created an API project yet, this page will ask you to do so: 3. If you already have existing projects, the first page you see will be the Dashboard page. From there you can create a new project by opening the project drop-down menu (upper left corner) and choosing Other projects > Create. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 5

6 4. After creating the project. Your browser URL will change to something like: You ll need to keep the value after #project: ( in this example). This is your project number, and it will be used later on as the GCM sender ID. 5. It is required now to enable the GCM service through the following steps: a. In the main Google APIs Console page, select Services. b. Turn the Google Cloud Messaging toggle to ON. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 6

7 c. In the Terms of Service page, accept the terms. 6. After enabling the service, the API key is required. To obtain it: In the main Google APIs Console page, select API Access. You will see a screen as like: How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 7

8 7. Click Create new Server key. Note that either a server key or a browser key should work. The advantage of using a server key is that it gives you more control on the IP addresses that can access your app (this feature is not used in our application below). The following screen appears, just click the Create button: 8. Take note with the API key that is shown after that: How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 8

9 9. Up to this step, you have finished creation of the Google API proejct and toke a note with the project number and the API key. For development, you ll need to install the helper libraries from the SDK manager as follow: From the SDK Manager, install Extras > Google Cloud Messaging for Android Library. This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcmclient, gcm-server, samples/gcm-demo-client, samples/gcm-demo-server, and samples/gcm-demo-appengine How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 9

10 3. How the GCM works? There are some key terms and concepts involved in the GCM service and it is very important to have a good knowledge about them. The key terms and concepts of the GCM are divided into two categories [2]: Components The physical items involved in GCM steps. Credentials The IDs that are used in different stages of GCM to achieve the authentication, and to be sure that the message is going to the correct application and the correct Android device. Table 1 below explains the previous GCM concepts with clear examples How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 10

11 Table 1 GCM concepts Components Mobile Devices The device that is running an Android application that uses GCM 3rd-party Application Server The 3rd-party application server sends data to an Android application on the device via the GCM server. GCM Servers The Google servers used in taking messages from the 3rdparty application server and sending them to the device. Credentials Sender ID A project number you acquire from the API console. The sender ID is used in the registration process to identify an Android application that is permitted to send messages to the device Application ID The Android application that is registering to receive messages. The Android application is identified by the package name from the manifest.xml file. This ensures that the messages are targeted to the correct Android application Registration ID An ID issued by the GCM servers to the Android application that allows it to receive messages. Once the Android application has the registration ID, it sends it to the 3rd-party application server, which uses it to identify each device that has registered to receive messages for a given Android application. In other words, a registration ID is tied to a particular Android application running on a particular device. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 11

12 Google User Account Sender Auth Token For GCM to work, the mobile device must include at least one Google account if the device is running a version lower than Android An API key that is saved on the 3rd-party application server that gives the application server authorized access to Google services. The API key is included in the header of POST requests that send messages GCM Lifecycle The usage of the GCM process requires the following phases: 1. Enabling GCM - An Android application running on a mobile device registers itself to be able to receive messages. 2. Sending a message - A 3rd-party application server sends messages to the device. 3. Receiving a message - An Android application receives a message from a GCM server. 4. Example of Android Application that Uses the GCM This section will explain an Android application used in the energy-aware smart home project developed by SECC. This app was based on the GCM demo application provided by Google [3]. We ll cover the details of that application with all of the code snapshots in the next section The android application architecture is described in Error! Reference source not ound.. It consists of three parts: 1. Application server App (Here called GCM server) 2. GCM client App (the Android App) 3. GCM cloud service The following is an explanation for the scenario shown in Error! Reference ource not found. 1. At the device start up, the installed Android app (GCM client) sends a registration request to the GCM server asking for a registration id. This registration request uses the Google API project ID to identify the Android device that asks for the registration id. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 12

13 2. The GCM server responds to the previous request and sends the registration id to the Android device. The Android app sends this registration id to server application which stores it in its internal storage. Figure 1 GCM application example in smart home building application 3. The fault detector KP is subscribed for smart home devices faults. When it detects any fault, it invokes the server application 4. The server application sends a message to the Android device, where it sends a request to the GCM server via its helper classes APIs including the Google API project ID and the server API key. 5. When the GCM server finds the Android device online, it ll pass the message to it through a broadcast intent. The broadcast receiver GCMIntentService intent in the Android device is responsible for receiving this broadcast message and invoking the notification manager How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 13

14 to create a new notification. First, we need to state the list of tools required to develop this App. Table 1 shows these tools Tool Eclipse Indigo or Eclipse Juno Android ADT plugin Apache Tomcat Application server v7.1or later Apache Ant 1.8 or later For the web server: Ant 1.8, it is a project building tool and it is used for building the serverside application as a.war file A running web server compatible with Servlets API version 2.5, such as Tomcat 7 Google account registered to use GCM. The API key for that account. For the Android application: Eclipse with the ADT plugin Emulator (or device) running Android 2.3 (Ginger-bread) or higher with Google APIs. The Google API project number of the account registered to use GCM. 5. Architecture of Android Application that uses GCM In this section, we ll cover in details the architecture of the Android app that uses the GCM service and also we ll cover the 3d party application server app GCM process flow As mentioned above the GCM service has three main steps: Enabling GCM Sending a message Receiving a message How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 14

15 Enabling GCM This is the sequence of events that occurs when an Android application running on a mobile device registers itself into the GCM server to receive messages: 1. The first time the Android application needs to use the messaging service, it sends registration intent to a GCM server. This registration Intent (com.google.android.c2dm.intent.register) includes the sender ID, and the Android application ID. 2. If the registration is successful, the GCM server broadcasts a com.google.android.c2dm.intent.registration intent which gives the Android application a registration ID. The Android application should store this ID for later use (for instance, to check on oncreate() if it is already registered). 3. To complete the registration, the Android application sends the registration ID to the application server. The application server stores the registration ID in a database Sending a message For an application server to send a message to an Android application, the following things must be in place: The Android application has a registration ID that allows it to receive messages for a particular device. The 3rd-party application server has stored the registration ID. An API key. It is a key for the application on the application server and it is previously set up in the api.key file that exists in the application server app that will be explained later. Here is the sequence of events that occurs when the application server sends a message: 1. The application server sends a message to GCM servers. 2. GCM servers store the message in case the device is offline. 3. When the device is online, Google sends the message to the device. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 15

16 Receiving a message This is the sequence of events that occurs when an Android application installed on a mobile device receives a message: 1. The system receives the incoming message and extracts any data from it, if any. 2. The system passes the key/value pairs to the targeted Android application in a com.google.android.c2dm.intent.receive Intent as a set of extras. 3. The Android application processes the message 5.2. Application server App The application server used here is the Apache Tomcat v7.0 which is a servlet container that can accept HTTP requests and send HTTP commands to the GCM server. We don t need to develop a new application server where the GCM Demo server application provided by Google can be used directly. The following steps explain how to use it: 1. From the SDK Manager, install Extras > Google Cloud Messaging for Android Library. 2. This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-server, samples/gcmdemo-client, samples/gcm-demo-server, and samples/gcm-demoappengine. 3. You can create a web application from Eclipse and copy the gcm-demoserver app into it as shown below 4. In a text editor or from inside Eclipse, edit the samples/gcm-demoserver/webcontent/web-inf/classes/api.key and replace the existing text (if any) with the API key obtained above. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 16

17 5. In a shell window, go to the samples/gcm-demo-server directory. 6. Generate the server's WAR file by running ant war: $ ant war Buildfile:build.xml init: [mkdir] Created dir: build/classes [mkdir] Created dir: dist compile: [javac] Compiling 6 source files to build/classes war: [war] Building war: dist/gcm-demo.war BUILD SUCCESSFUL Total time: 0 seconds Now the.war file is ready to be deployed into your application server, For instance, if you're using Tomcat as in our case, copy gcm-demo.war to the ${CATALINA_HOME/webapps directory of the Tomcat installation. Starting the Tomcat will make this application running waiting for inquires that will be sent to it from the invoker app that will be explained later. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 17

18 For more information about how the 3 rd party application server works, and how it sends messages either in text or JSON format, you can refer to [2] 5.3 Android App To write Android applications that use GCM, you must have an application server described above. This section describes the steps you take to create a client application that uses GCM. Our client app is based on the gcm-demo-client app that exists in YOUR_SDK_ROOT/extras/google/samples You can follow these steps to use the gcm-demo-client app: 1- Create new Android project in Eclipse with the name gcm-demo-client 2- Copy the package com.google.android.gcm.demo.app from YOUR_SDK_ROOT/extras/google/samples/gcm-demo-client and paste it in the eclipse project 3- Add the gcm.jar file into your project s libs 1 directory (this is done by just copying it into libs folder) 4- Open the AndroidManifest.xml from YOUR_SDK_ROOT/extras/google/samples/gcm-demo-client and copy its contents in the AndroidManifest.xml file in your local eclipse project You must see now the following project structure: 1 The libs directory is by default existing in the project class path so if you don t want to add gcm.jar in this directory, you ll just need to add the path of it into your class path How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 18

19 There are two primary steps involved in writing a client Android application: Creating a manifest that contains the permissions the Android application needs to use GCM. Implementing your code. To use GCM, this implementation must include: o Code to start and stop the registration service. o Receivers for the com.google.android.c2dm.intent.receive and com.google.android.c2dm.intent.registration intents Creating the Manifest file Every Android application must have an AndroidManifest.xml file in its root directory. The manifest presents essential information about the Android application to the Android system. To use the GCM feature, the manifest must include the following: The com.google.android.c2dm.permission.receive permission so the Android application can register itself and receive messages. The android.permission.internet permission so the Android application can send the registration ID to the 3rd party server. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 19

20 The android.permission.get_accounts permission as GCM requires a Google account (necessary only if the device is running a version lower than Android ICS 4.0.4) The android.permission.wake_lock permission so the application can keep the processor from sleeping when a message is received. An application package + ".permission.c2d_message permission to prevent other Android applications from registering and receiving the Android application's messages. The permission name must exactly match this pattern otherwise the Android application will not receive the messages. A receiver for com.google.android.c2dm.intent.receive and com.google.android.c2dm.intent.registration, with the category set as application package. The receiver should require the com.google.android.c2dm.send permission, to ensure that only intents sent by the GCM system framework are sent to the receiver (a regular application cannot issue intents with that permission). This broadcast receiver is responsible for handling the above 2 intents that can be sent by GCM (com.google.android.c2dm.intent.receive and com.google.android.c2dm.intent.registration) and it is defined here in the manifest file so that these intents can be received even if the application is not running. An intent service to handle the intents received by the broadcast receiver. This intent service will be called by the GCMBroadcastReceiver (which is provided by the GCM library). It could be a subclass of com.google.android.gcm.gcmbaseintentservice, and it must contain a public constructor, and should be named my_app_package.gcmintentservice Set android:minsdkversion="8" in the manifest. This ensures that the Android application cannot be installed in an environment in which it could not run properly. Here s the AndroidManifest.xml file of the gcm-demo-client project How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 20

21 <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android=" package="com.google.android.gcm.demo.app" android:versioncode="1" android:versionname="1.0" > <uses-sdk android:minsdkversion="8" android:targetsdkversion="16"/> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.get_accounts" /> <uses-permission android:name="android.permission.wake_lock" /> <permission android:name="com.google.android.gcm.demo.app.permission.c2d_message" android:protectionlevel="signature" /> <uses-permission android:name="com.google.android.gcm.demo.app.permission.c2d_message" /> <!-- This app has permission to register and receive data message. --> <uses-permission android:name="com.google.android.c2dm.permission.receive" /> <!-- Main activity. --> <application > <activity android:name=".demoactivity" android:screenorientation="portrait" > <intent-filter> <action android:name="android.intent.action.main" /> <category android:name="android.intent.category.launcher" /> </intent-filter> </activity> <receiver android:name="com.google.android.gcm.gcmbroadcastreceiver" android:permission="com.google.android.c2dm.permission.send" > <intent-filter> <!-- Receives the actual messages. --> <action android:name="com.google.android.c2dm.intent.receive" /> <!-- Receives the registration id. --> <action android:name="com.google.android.c2dm.intent.registration" /> <category android:name="com.google.android.gcm.demo.app" /> </intent-filter> </receiver> <service android:name=".gcmintentservice" /> </application> </manifest> How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 21

22 5.3.2 Android app structure The client application is consisting of 4 files: 1. CommonUtilities.java This file includes the definitions of two main variables SERVER_URL, the server app url for e.g., SENDER_ID, Google API project ID This file will look like this: package com.google.android.gcm.demo.app; import android.content.context; import android.content.intent; /** * Helper class providing methods and constants common to other classes in the * app. */ public final class CommonUtilities { /** * Base URL of the Demo Server (such as */ static final String SERVER_URL = " /** * Google API project id registered to use GCM. */ static final String SENDER_ID = " "; /** * Tag used on log messages. */ static final String TAG = "GCMDemo"; /** * Intent used to display a message in the screen. */ static final String DISPLAY_MESSAGE_ACTION = "com.google.android.gcm.demo.app.display_message"; /** * Notifies UI to display a message. * <p> * This method is defined in the common helper because it's used both by How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial * the UI and the background service. Page 22 * context application's context. message message to be displayed. */

23 /** * Intent's extra that contains the message to be displayed. */ static final String EXTRA_MESSAGE = "message"; /** * Notifies UI to display a message. * <p> * This method is defined in the common helper because it's used both by * the UI and the background service. * context application's context. message message to be displayed. */ static void displaymessage(context context, String message) { Intent intent = new Intent(DISPLAY_MESSAGE_ACTION); intent.putextra(extra_message, message); context.sendbroadcast(intent); 2. GCMIntentService.java This class extends GCMBaseIntentService and it represents the intent service responsible for handling GCM messages. In this class we are overriding the following callback methods (which are called by GCMBroadcastReceiver): onregistered(context context, String regid): Called after a registration intent is received, passes the registration ID assigned by GCM to that device/application pair as parameter. Typically, you should send the regid to your server so it can use it to send messages to this device. onunregistered(context context, String regid): Called after the device has been unregistered from GCM. Typically, you should send the regid to the server so it unregisters the device. onmessage(context context, Intent intent): Called when your server sends a message to GCM, and GCM delivers it to the device. If the message has a payload, its contents are available as extras in the intent. onerror(context context, String errorid): Called when the device tries to register or unregister, but GCM returned an error. Typically, there is nothing to be done other than evaluating the error (returned by errorid) and trying to fix the problem. onrecoverableerror(context context, String errorid): Called when the device tries to register or unregister, but the GCM How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 23

24 Log.i(TAG, "Ignoring unregister protected void onmessage(context context, Intent intent) { Log.i(TAG, "Received message"); String message = getstring(r.string.gcm_message); displaymessage(context, message); // notifies user with the new messages generatenotification(context, protected void ondeletedmessages(context context, int total) { Log.i(TAG, "Received deleted messages notification"); String message = getstring(r.string.gcm_deleted, total); displaymessage(context, message); // notifies user generatenotification(context, public void onerror(context context, String errorid) { Log.i(TAG, "Received error: " + errorid); displaymessage(context, getstring(r.string.gcm_error, protected boolean onrecoverableerror(context context, String errorid) { // log message Log.i(TAG, "Received recoverable error: " + errorid); displaymessage(context, getstring(r.string.gcm_recoverable_error, errorid)); return super.onrecoverableerror(context, errorid); /** * Issues a notification to inform the user that server has sent a message. */ private static void generatenotification(context context, String message) { int icon = R.drawable.ic_stat_gcm; long when = System.currentTimeMillis(); NotificationManager notificationmanager = (NotificationManager) context.getsystemservice(context.notification_service); Notification notification = new Notification(icon, message, when); String title = context.getstring(r.string.app_name); Intent notificationintent = new Intent("android.intent.action.VIEW", Uri.parse(" // set intent so it does not start a new activity notificationintent.setflags(intent.flag_activity_clear_top Intent.FLAG_ACTIVITY_SINGLE_TOP); PendingIntent intent = PendingIntent.getActivity(context, 0, notificationintent, 0); notification.setlatesteventinfo(context, title, message, intent); notification.flags = Notification.FLAG_AUTO_CANCEL; notificationmanager.notify(0, notification); How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 24

25 servers are unavailable. The GCM library will retry the operation using exponential backup, unless this method is overridden and returns false. This method is optional and should be overridden only if you want to display the message to the user or cancel the retry attempts. This file will look like this: package com.google.android.gcm.demo.app; import static com.google.android.gcm.demo.app.commonutilities.sender_id; import static com.google.android.gcm.demo.app.commonutilities.displaymessage; import android.app.notification; import android.app.notificationmanager; import android.app.pendingintent; import android.content.context; import android.content.intent; import android.net.uri; import android.util.log; import com.google.android.gcm.gcmbaseintentservice; import com.google.android.gcm.gcmregistrar; /** * IntentService responsible for handling GCM messages. */ public class GCMIntentService extends GCMBaseIntentService private static final String TAG = "GCMIntentService"; public GCMIntentService() { protected void onregistered(context context, String registrationid) { Log.i(TAG, "Device registered: regid = " + registrationid); displaymessage(context, getstring(r.string.gcm_registered)); ServerUtilities.register(context, protected void onunregistered(context context, String registrationid) { Log.i(TAG, "Device unregistered"); displaymessage(context, getstring(r.string.gcm_unregistered)); if (GCMRegistrar.isRegisteredOnServer(context)) { ServerUtilities.unregister(context, registrationid); else { // This callback results from the call to unregister made on // ServerUtilities when the registration to the server failed. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 25

26 3. ServerUtilities.java This is a helper class used to enable the Android app to communicate with the application server. It contains three methods called: register() Posts the registration request to the register servlet deployed at the application server, this servlet accepts the request and stores the registration id in its database. unregister() Posts the unregister request to the unregister servlet deployed at the application server, this servlet accepts the request and removes the registration id from its database. Post() Posts the register or unregister request to the application server This file will look like this: How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 26

27 package com.google.android.gcm.demo.app; import static com.google.android.gcm.demo.app.commonutilities.server_url; import static com.google.android.gcm.demo.app.commonutilities.tag; import static com.google.android.gcm.demo.app.commonutilities.displaymessage; import com.google.android.gcm.gcmregistrar; import android.content.context; import android.util.log; import java.io.ioexception; import java.io.outputstream; import java.net.httpurlconnection; import java.net.malformedurlexception; import java.net.url; import java.util.hashmap; import java.util.iterator; import java.util.map; import java.util.map.entry; import java.util.random; /** * Helper class used to communicate with the demo server. */ public final class ServerUtilities { private static final int MAX_ATTEMPTS = 5; private static final int BACKOFF_MILLI_SECONDS = 2000; private static final Random random = new Random(); /** * Register this account/device pair within the server. * whether the registration succeeded or not. */ static boolean register(final Context context, final String regid) { Log.i(TAG, "registering device (regid = " + regid + ")"); String serverurl = SERVER_URL + "/register"; Map<String, String> params = new HashMap<String, String>(); params.put("regid", regid); long backoff = BACKOFF_MILLI_SECONDS + random.nextint(1000); for (int i = 1; i <= MAX_ATTEMPTS; i++) { Log.d(TAG, "Attempt #" + i + " to register"); try { displaymessage(context, context.getstring( R.string.server_registering, i, MAX_ATTEMPTS)); post(serverurl, params); GCMRegistrar.setRegisteredOnServer(context, true); String message = context.getstring(r.string.server_registered); CommonUtilities.displayMessage(context, message); return true; catch (IOException e) { Log.e(TAG, "Failed to register on attempt " + i, e); if (i == MAX_ATTEMPTS) { break; try { Log.d(TAG, "Sleeping for " + backoff + " ms before retry"); Thread.sleep(backoff); catch (InterruptedException e1) { // Activity finished before we complete - exit. Log.d(TAG, "Thread interrupted: abort remaining retries!"); Thread.currentThread().interrupt(); return false; How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 27 // increase backoff exponentially backoff *= 2;

28 Log.d(TAG, "Thread interrupted: abort remaining retries!"); Thread.currentThread().interrupt(); return false; // increase backoff exponentially backoff *= 2; String message = context.getstring(r.string.server_register_error, MAX_ATTEMPTS); CommonUtilities.displayMessage(context, message); return false; /** * Unregister this account/device pair within the server. */ static void unregister(final Context context, final String regid) { Log.i(TAG, "unregistering device (regid = " + regid + ")"); String serverurl = SERVER_URL + "/unregister"; Map<String, String> params = new HashMap<String, String>(); params.put("regid", regid); try { post(serverurl, params); GCMRegistrar.setRegisteredOnServer(context, false); String message = context.getstring(r.string.server_unregistered); CommonUtilities.displayMessage(context, message); catch (IOException e) { // At this point the device is unregistered from GCM, but still // registered in the server. // We could try to unregister again, but it is not necessary: // if the server tries to send a message to the device, it will get // a "NotRegistered" error message and should unregister the device. String message = context.getstring(r.string.server_unregister_error, e.getmessage()); CommonUtilities.displayMessage(context, message); How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 28

29 /** * Issue a POST request to the server. * endpoint POST address. params request parameters. * IOException propagated from POST. */ private static void post(string endpoint, Map<String, String> params) throws IOException { URL url; try { url = new URL(endpoint); catch (MalformedURLException e) { throw new IllegalArgumentException("invalid url: " + endpoint); StringBuilder bodybuilder = new StringBuilder(); Iterator<Entry<String, String>> iterator = params.entryset().iterator(); // constructs the POST body using the parameters while (iterator.hasnext()) { Entry<String, String> param = iterator.next(); bodybuilder.append(param.getkey()).append('=').append(param.getvalue()); if (iterator.hasnext()) { bodybuilder.append('&'); String body = bodybuilder.tostring(); Log.v(TAG, "Posting '" + body + "' to " + url); byte[] bytes = body.getbytes(); HttpURLConnection conn = null; try { conn = (HttpURLConnection) url.openconnection(); conn.setdooutput(true); conn.setusecaches(false); conn.setfixedlengthstreamingmode(bytes.length); conn.setrequestmethod("post"); conn.setrequestproperty("content-type", "application/x-www-form-urlencoded;charset=utf-8"); // post the request OutputStream out = conn.getoutputstream(); out.write(bytes); out.close(); // handle the response int status = conn.getresponsecode(); if (status!= 200) { Log.d(TAG, "Post failed with error code"); throw new IOException("Post failed with error code " + status); finally { if (conn!= null) { conn.disconnect(); 1. DemoActivity.java This class is the main UI of the application; it handles the registration of the Android device when the activity starts How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 29

30 4. DemoActivity.java This class is the main UI of the application; it handles the registration of the Android device when the activity starts 4.1 Application registration: An Android application needs to register with GCM servers before it can receive messages. To register, the application sends Intent (com.google.android.c2dm.intent.register), with 2 extra parameters: o Sender is the project number of the account authorized to send messages to the Android application. o App is the Android application's ID, set with a PendingIntent to allow the registration service to extract Android application information. This registration can be done easily using the GCMRegstrar object GCMRegistrar.register(this, SENDER_ID); This intent will be asynchronously sent to the GCM server, and the response will be delivered to the application as a com.google.android.c2dm.intent.registration intent containing the registration ID assigned to the Android application running on that particular device. Registration is not complete until the Android application sends the registration ID to the 3rd-party application server, which in turn will use the registration ID to send messages to the application. This is done by calling ServerUtilities.register(context, regid); 4.2 Handling GCM intents: The manifest defines a broadcast receiver for the com.google.android.c2dm.intent.registration and com.google.android.c2dm.intent.receive intents. These intents are sent by GCM to indicate that a device was registered (or unregistered), or to deliver messages, respectively. How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 30

31 Handling these intents might require I/O operations (such as network calls to the 3rd party server), and such operations should not be done in the receiver's onreceive() method. The recommended way to handle the intents is to delegate them to a service, such as a GCMIntentService explained above. This file will look like this: package com.google.android.gcm.demo.app; import static com.google.android.gcm.demo.app.commonutilities.display_message_action; import static com.google.android.gcm.demo.app.commonutilities.extra_message; import static com.google.android.gcm.demo.app.commonutilities.sender_id; import static com.google.android.gcm.demo.app.commonutilities.server_url; import com.google.android.gcm.gcmregistrar; import android.app.activity; import android.content.broadcastreceiver; import android.content.context; import android.content.intent; import android.content.intentfilter; import android.graphics.color; import android.net.uri; import android.os.asynctask; import android.os.bundle; import android.util.log; import android.view.menu; import android.view.menuinflater; import android.view.menuitem; import android.view.view; import android.widget.button; import android.widget.textview; /** * Main UI for the demo app. */ public class DemoActivity extends Activity { TextView mdisplay; Button websitebutton; AsyncTask<Void, Void, Void> mregistertask; private static final String TAG = public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); checknotnull(server_url, "SERVER_URL"); checknotnull(sender_id, "SENDER_ID"); // Make sure the device has the proper dependencies. GCMRegistrar.checkDevice(this); // Make sure the manifest was properly set - comment out this line // while developing the app, then uncomment it when it's ready. How To Develop GCMRegistrar.checkManifest(this); Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 31 setcontentview(r.layout.main); websitebutton=(button)findviewbyid(r.id.websitebutton); websitebutton.setonclicklistener(new View.OnClickListener(){

32 // Make sure the device has the proper dependencies. GCMRegistrar.checkDevice(this); // Make sure the manifest was properly set - comment out this line GCMRegistrar.checkManifest(this); setcontentview(r.layout.main); websitebutton=(button)findviewbyid(r.id.websitebutton); websitebutton.setonclicklistener(new View.OnClickListener(){ public void onclick(view v){ Intent intent = new Intent(); intent.setaction(intent.action_view); intent.addcategory(intent.category_browsable); intent.setdata(uri.parse(" startactivity(intent); ); mdisplay = (TextView) findviewbyid(r.id.display); mdisplay.settext("\nsmart Home Notifier Application will send you a notifications in case of " + "faults occured with your home devices." + "The application is based on Google Cloud Messaging Service (GCM).\n" + "The scenario is as follow:\n" +" 1- In case of fault occured, a fault detector web service will be invoked. This web service sends the fault message to the GCM server via a web application deployed in the application server\n" + " 2- The GCM server receives the message and routes it to the target Application which is running on your device.\n" + "**Developed by: SECC R&D Team. mdisplay.settextcolor(color.white); mdisplay.append("log:"); registerreceiver(mhandlemessagereceiver, new IntentFilter(DISPLAY_MESSAGE_ACTION)); final String regid = GCMRegistrar.getRegistrationId(this); if (regid.equals("")) { // Automatically registers application on startup. GCMRegistrar.register(this, SENDER_ID); Log.d(TAG, "Registered to GCM!!! "); else { // Device is already registered on GCM, check server. if (GCMRegistrar.isRegisteredOnServer(this)) { // Skips registration. mdisplay.append(getstring(r.string.already_registered) + "\n"); else { // Try to register again, but not in the UI thread. // It's also necessary to cancel the thread ondestroy(), // hence the use of AsyncTask instead of a raw thread. final Context context = this; mregistertask = new AsyncTask<Void, Void, Void>() protected Void doinbackground(void... params) { boolean registered = ServerUtilities.register(context, regid); if (!registered) { GCMRegistrar.unregister(context); How To Develop Smart Android return Notifications null; using Google Cloud Messaging Service Tutorial Page protected void onpostexecute(void result) {

33 if (!registered) { GCMRegistrar.unregister(context); return protected void onpostexecute(void result) { mregistertask = null; ; mregistertask.execute(null, null, public boolean oncreateoptionsmenu(menu menu) { MenuInflater inflater = getmenuinflater(); inflater.inflate(r.menu.options_menu, menu); return public boolean onoptionsitemselected(menuitem item) { switch(item.getitemid()) { case R.id.options_clear: mdisplay.settext(null); return true; case R.id.options_exit: finish(); return true; default: return protected void ondestroy() { if (mregistertask!= null) { mregistertask.cancel(true); unregisterreceiver(mhandlemessagereceiver); GCMRegistrar.onDestroy(this); super.ondestroy(); How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 33

34 private void checknotnull(object reference, String name) { if (reference == null) { throw new NullPointerException( getstring(r.string.error_config, name)); private final BroadcastReceiver mhandlemessagereceiver = new BroadcastReceiver() public void onreceive(context context, Intent intent) { String newmessage = intent.getextras().getstring(extra_message); mdisplay.append(newmessage + "\n"); ; After developing the above application, you can now run the project to get the.apk file and install it in your Android-powered device. When running this application you will see a screen like this: N.B: You must make sure that the application server app (gc-demo-server.war) is deployed and running on tomcat 6. Invoker Application Up till now, you have both Android and the Application server apps running. In order to test the whole cycle you ll need to develop an invoker application that How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 34

35 calls the application server app and asks it to send a message to the Android app. Once this message is received, the Android app will fire a notification for the user. In the practical cases, this invoker app is your end application that needs based on some logic to send notifications to the Android-powered device Invoker example architecture The invoker explained in this tutorial is composed of two files: 1. Definitions.java This file is simply contains the project ID, it will look as follow: package com.secc.sendnotificationviagcmservice; public final class Definitions { static final String SERVER_URL = " /** * Google API project id registered to use GCM. */ static final String SENDER_ID = " "; 2. InvokeSendAllServlet.java This file is the core invoker which calls the sendall servlet of the application server which is responsible for contacting the GCM server and asking it to send messages to the Android application. This file could be like this: How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 35

36 package com.secc.sendnotificationviagcmservice; import static com.secc.sendnotificationviagcmservice.definitions.server_url; import java.io.ioexception; import java.io.outputstream; import java.net.httpurlconnection; import java.net.malformedurlexception; import java.net.url; public class InvokeSendAllServlet { public void invokesendallservlet() { String serverurl = SERVER_URL + "/sendall"; try { post(serverurl); catch (IOException e) { private static void post(string endpoint) throws IOException { URL url; try { url = new URL(endpoint); catch (MalformedURLException e) { throw new IllegalArgumentException("invalid url: " + endpoint); HttpURLConnection conn = null; try { conn = (HttpURLConnection) url.openconnection(); conn.setdooutput(true); conn.setusecaches(false); conn.setrequestmethod("post"); conn.setrequestproperty("content-type", "application/x-www-form-urlencoded;charset=utf-8"); OutputStream out = conn.getoutputstream(); out.close(); int status = conn.getresponsecode(); if (status!= 200) { throw new IOException("Post failed with error code " + status); finally { if (conn!= null) { conn.disconnect(); public static void main(string []args) { InvokeSendAllServlet invoke=new InvokeSendAllServlet(); invoke.invokesendallservlet(); How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 36

37 By running the above invoker app you should see a notification appeared. 7. Summary Google Cloud Messaging for Android (GCM) is a free and powerful service that helps developers to send data from servers to their Android applications running on Android-powered devices. This tutorial provides the basic concepts of this service with a detailed explanation of the GCM demo application provided by the Android SDK. The GCM service is very promising and it could be How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 37

38 8. References considered the most optimized and powerful method for sending messages from servers to the Android devices without the need to have the Android application listens to the server in an endless loop. 9. Abbreviations [1] [2] [3] GCM App HTTP API C2DM KP Google Cloud Messaging Application Hypertext Transfer Protocol Application Programming Interface Cloud to Device Messaging Knowledge Processor How To Develop Smart Android Notifications using Google Cloud Messaging Service Tutorial Page 38