public class

GoogleCloudMessaging

extends Object
java.lang.Object
   ↳ com.google.android.gms.gcm.GoogleCloudMessaging

Class Overview

Google Cloud Messaging for Android.

This class requires Google Play services version 3.1 or higher.

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.

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 the 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>

To send or receive messages, you first need to get a registration ID. The registration ID identifies the device and application, as well as which servers are allowed to send messages.

 GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(context);

 String registrationId = gcm.register(sender1, sender2);
 // Upload the registrationId to your own server
 // The request to your server should be authenticated if your app is using accounts.
 

The BroadcastReceiver will be invoked whenever a message is received, as well as for special messages generated by GCM. Within the BroadcastReceiver you can call getMessageType(Intent).

To send messages, call send():

 gcm.send(to, msgId, data);
 

Summary

Constants
String ERROR_MAIN_THREAD GCM methods are blocking.
String ERROR_SERVICE_NOT_AVAILABLE The device can't read the response, or there was a 500/503 from the server that can be retried later.
String MESSAGE_TYPE_DELETED Returned by getMessageType(Intent) to indicate that the server deleted some pending messages because they were collapsible.
String MESSAGE_TYPE_MESSAGE Returned by getMessageType(Intent) to indicate a regular message.
String MESSAGE_TYPE_SEND_ERROR Returned by getMessageType(Intent) to indicate a send error.
Public Constructors
GoogleCloudMessaging()
Public Methods
void close()
Must be called when your application is done using GCM, to release internal resources.
synchronized static GoogleCloudMessaging getInstance(Context context)
Return the singleton instance of GCM.
String getMessageType(Intent intent)
Return the message type.
String register(String... senderIds)
Register the application for GCM and return the registration ID.
void send(String to, String msgId, long timeToLive, Bundle data)
Send a "device to cloud" message.
void send(String to, String msgId, Bundle data)
Send a "device to cloud" message.
void unregister()
Unregister the application.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ERROR_MAIN_THREAD

GCM methods are blocking. You should not run them in the main thread or in broadcast receivers.

Constant Value: "MAIN_THREAD"

public static final String ERROR_SERVICE_NOT_AVAILABLE

The device can't read the response, or there was a 500/503 from the server that can be retried later. The application should use exponential back off and retry.

Constant Value: "SERVICE_NOT_AVAILABLE"

public static final String MESSAGE_TYPE_DELETED

Returned by getMessageType(Intent) to indicate that the server deleted some pending messages because they were collapsible.

Constant Value: "deleted_messages"

public static final String MESSAGE_TYPE_MESSAGE

Returned by getMessageType(Intent) to indicate a regular message.

Constant Value: "gcm"

public static final String MESSAGE_TYPE_SEND_ERROR

Returned by getMessageType(Intent) to indicate a send error. The intent includes the message ID of the message and an error code.

Constant Value: "send_error"

Public Constructors

public GoogleCloudMessaging ()

Public Methods

public void close ()

Must be called when your application is done using GCM, to release internal resources.

public static synchronized GoogleCloudMessaging getInstance (Context context)

Return the singleton instance of GCM.

public String getMessageType (Intent intent)

Return the message type. Regular messages from the server have the type GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE. The server may also send special messages. The possible types are:

Additional types may be added later; you should ignore any type you don't handle.

Returns
  • the message type or null if the intent is not a GCM intent

public String register (String... senderIds)

Register the application for GCM and return the registration ID. You must call this once, when your application is installed, and send the returned registration ID to the server.

Repeated calls to this method will return the original registration ID.

If you want to modify the list of senders, you must call unregister() first.

Most applications use a single sender ID. You may use multiple senders if different servers may send messages to the app or for testing.

Parameters
senderIds list of project numbers or Google accounts identifying who is allowed to send messages to this application.
Returns
  • registration id
Throws
IOException

public void send (String to, String msgId, long timeToLive, Bundle data)

Send a "device to cloud" message. The current limits for max storage time and number of outstanding messages per application are documented in the GCM Dev Guide.

Parameters
to string identifying the receiver of the message. For GCM projects IDs the value is SENDER_ID@gcm.googleapis.com. The SENDER_ID should be one of the sender IDs used in register().
msgId ID of the message. This is generated by the application. It must be unique for each message. This allows error callbacks and debugging.
timeToLive If 0, we'll attempt to send immediately and return an error if we're not connected. Otherwise, the message will be queued. As for server-side messages, we don't return an error if the message has been dropped because of TTL—this can happen on the server side, and it would require extra communication.
data key/value pairs to be sent. Values must be String, any other type will be ignored.
Throws
IOException

public void send (String to, String msgId, Bundle data)

Send a "device to cloud" message. The message will be queued if we don't have an active connection for the max interval.

Parameters
to string identifying the receiver of the message. For GCM project IDs the value is SENDER_ID@gcm.googleapis.com. The SENDER_ID should be one of the sender IDs used in register().
msgId ID of the message. This is generated by the application. It must be unique for each message. This allows error callbacks and debugging.
data key/value pairs to be sent. Values must be String—any other type will be ignored.
Throws
IOException

public void unregister ()

Unregister the application. Calling unregister() stops any messages from the server. This is a blocking call—you shouldn't call it from the UI thread. You should rarely (if ever) need to call this method. Not only is it expensive in terms of resources, but it invalidates your registration ID, which should never change unnecessarily. A better approach is to simply have your server stop sending messages. Only use unregister if you want your application to stop using GCM permanently, or you have a compelling reason to recycle your registration ID.

Throws
IOException if we can't connect to server to unregister.