GoogleCloudMessaging

Class Overview

The class you use to write a GCM-enabled client application that runs on an Android device. Client applications can receive GCM messages and optionally send messages of their own back to the server.

This class requires Google Play services version 3.1 or higher. For a detailed discussion of how to write a GCM client app, see Implementing GCM Client.

To send or receive messages, your application first needs to get a registration ID. The registration ID identifies the device and application, and also determines which 3rd-party application servers are allowed to send messages to this application instance.

To get a registration ID, you must supply one or more sender IDs. A sender ID is a project number you acquire from the API console, as described in Getting Started. The sender ID is used in the registration process to identify a 3rd-party application server that is permitted to send messages to the device. The following snippet shows you how to call the register() method. For a more comprehensive example, see Implementing GCM Client.

 String SENDER_ID = "My-Sender-ID";
 GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(context);
 String registrationId = gcm.register(SENDER_ID);
 // Upload the registration ID to your own server
 // The request to your server should be authenticated if your app is using accounts.
 

In order to receive GCM messages, you need to declare a permission and a BroadcastReceiver in your manifest. This is a backward-compatible subset of what was required in previous versions of GCM.

To allow the application to use GCM, add this permission to the manifest:

<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

GCM delivers messages as a broadcast. The receivers must be registered in the manifest in order to wake up the application.

The com.google.android.c2dm.permission.SEND permission is held by Google Play services. This prevents other code from invoking the broadcast receiver. Here is an excerpt from a sample manifest:

 <receiver android:name=".MyReceiver" android:exported="true"
     android:permission="com.google.android.c2dm.permission.SEND" >
     <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="YOUR_PACKAGE_NAME" />
     </intent-filter>
 </receiver>

When a GCM connection server delivers the message to your client app, the BroadcastReceiver receives the message as an intent. You can either process the intent in the BroadcastReceiver, or you can pass off the work of processing the intent to a service (typically, an IntentService). If you use a service, your broadcast receiver should be an instance of WakefulBroadcastReceiver, to hold a wake lock while the service is doing its work.

When processing the intent GCM passes into your app's broadcase receiver, you can determine the message type by calling getMessageType(intent). For example:

 GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(this);
 String messageType = gcm.getMessageType(intent);
 ...
 // Filter messages based on message type. It is likely that GCM will be extended in the future
 // with new message types, so just ignore message types you're not interested in, or that you
 // don't recognize.
 if (GoogleCloudMessaging.MESSAGE_TYPE_SEND_ERROR.equals(messageType)) {
    // It's an error.
 } else if (GoogleCloudMessaging.MESSAGE_TYPE_DELETED.equals(messageType)) {
    // Deleted messages on the server.
 } else if (GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE.equals(messageType)) {
    // It's a regular GCM message, do some work.
 }
 

If you are using the XMPP-based Cloud Connection Server, your client app can send upstream messages back to the server. For example:

 gcm.send(SENDER_ID + "@gcm.googleapis.com", id, data);
 

Summary

[Expand] Inherited Methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait() final void wait(long arg0, int arg1) final void wait(long arg0)