Summary: Constants | Ctors | Methods | Inherited Methods | [Expand All]
public class

# GoogleCloudMessaging

extends Object

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

## Class Overview

Google Cloud Messaging (GCM) is now part of Firebase and has been rebranded as Firebase Cloud Messaging (FCM).

Google offers a new FCM SDK that simplifies client implementation. The FCM SDK provides out-of-the-box support for Firebase Notifications console and Firebase Analytics so that anyone can send notifications and measure their effectiveness without setting up a server.

See the documentation for FCM and Firebase Notifications for more info.

Google will continue to support the existing version of the GCM SDK.

To send or receive messages, the app must get a registrationToken from `getToken(String, String)`, which authorizes an app server to send messages to an app instance. Pass sender ID and `INSTANCE_ID_SCOPE` as parameters to the method. A sender ID is a project number acquired from the API console, as described in Getting Started.

In order to receive GCM messages, declare `GcmReceiver` and an implementation of `GcmListenerService` in the app manifest. `GcmReceiver` will pass the incoming messages to the implementation of `GcmListenerService`. To process messages, override base class methods to handle any events required by the application.

Client apps can send upstream messages back to the app server using the XMPP-based Cloud Connection Server, For example:

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

See Implementing GCM Client on Android for more details.

## Summary

Constants
String | ERROR_MAIN_THREAD | The GCM `register()` and `unregister()` 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 | INSTANCE_ID_SCOPE | Specifies scope used in obtaining GCM registrationToken when calling `getToken(String, String)`
String | MESSAGE_TYPE_DELETED | This constant is deprecated. Instead implement `onDeletedMessages()`
String | MESSAGE_TYPE_MESSAGE | This constant is deprecated. Instead implement `onMessageReceived(String, Bundle)`
String | MESSAGE_TYPE_SEND_ERROR | This constant is deprecated. Instead implement `onSendError(String, String)`
String | MESSAGE_TYPE_SEND_EVENT | This constant is deprecated. Instead implement `onMessageSent(String)`

Public Constructors
| GoogleCloudMessaging()

Public Methods
void | close() Must be called when your application is done using GCM, to release internal resources.
static GoogleCloudMessaging | getInstance(Context context) Return the singleton instance of GCM.
String | getMessageType(Intent intent) Return the message type from an intent passed into a client app's broadcast receiver.
String | register(String... senderIds) This method is deprecated. Instead, for GCM registration, use `InstanceID.getToken()`. Set authorizedEntity to a sender ID and scope to `INSTANCE_ID_SCOPE`.
void | send(String to, String msgId, Bundle data) Send an upstream ("device to cloud") message.
void | send(String to, String msgId, long timeToLive, Bundle data) Send an upstream ("device to cloud") message.
void | unregister() This method is deprecated. Instead use `InstanceID.deleteToken()` or `InstanceID.deleteInstanceID()`.

[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(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()

## Constants

#### public static final String ERROR_MAIN_THREAD

The GCM `register()` and `unregister()` methods are blocking. Blocking methods must not be called on the main thread.

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 INSTANCE_ID_SCOPE

Specifies scope used in obtaining GCM registrationToken when calling `getToken(String, String)`

Constant Value: "GCM"

#### public static final String MESSAGE_TYPE_DELETED

This constant is deprecated.
Instead implement `onDeletedMessages()`

Returned by `getMessageType(Intent)` to indicate that the server deleted some pending messages because they exceeded the storage limits. The application should contact the server to retrieve the discarded messages.

Constant Value: "deleted_messages"

#### public static final String MESSAGE_TYPE_MESSAGE

This constant is deprecated.
Instead implement `onMessageReceived(String, Bundle)`

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

Constant Value: "gcm"

#### public static final String MESSAGE_TYPE_SEND_ERROR

This constant is deprecated.
Instead implement `onSendError(String, String)`

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 static final String MESSAGE_TYPE_SEND_EVENT

This constant is deprecated.
Instead implement `onMessageSent(String)`

Returned by `getMessageType(Intent)` to indicate a sent message has been received by the GCM server. The intent includes the message ID of the message.

Constant Value: "send_event"

## 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 GoogleCloudMessaging getInstance (Context context)

Return the singleton instance of GCM.

#### public String getMessageType (Intent intent)

Return the message type from an intent passed into a client app's broadcast receiver. There are two general categories of messages passed from the server: regular GCM messages, and special GCM status messages. The possible types are:

- `MESSAGE_TYPE_MESSAGE`—regular message from your server.
- `MESSAGE_TYPE_DELETED`—special status message indicating that some messages have been discarded because they exceeded the storage limits.
- `MESSAGE_TYPE_SEND_ERROR`—special status message indicating that there were errors sending one of the messages.

You can use this method to filter based on message type. Since it is likely that GCM will be extended in the future with new message types, just ignore any message types you're not interested in, or that you don't recognize.

##### Returns

- The message type or null if the intent is not a GCM intent

#### public String register (String... senderIds)

This method is deprecated.
Instead, for GCM registration, use `InstanceID.getToken()`. Set authorizedEntity to a sender ID and scope to `INSTANCE_ID_SCOPE`.

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, Bundle data)

Send an upstream ("device to cloud") message. You can only use the upstream feature if your GCM implementation uses the XMPP-based Cloud Connection Server. When there is an active connection the message will be sent immediately, otherwise the message will be queued for the maximum interval.

##### Parameters

to | string identifying the receiver of the message in the format of `SENDER_ID@gcm.googleapis.com`. The `SENDER_ID` should be one of the sender IDs used when calling `getToken(String, String)`
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

| IllegalArgumentException
IOException |

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

Send an upstream ("device to cloud") message. You can only use the upstream feature if your GCM implementation uses the XMPP-based Cloud Connection Server. The current limits for max storage time and number of outstanding messages per application are documented in the GCM Developers Guide.

##### Parameters

to | string identifying the receiver of the message in the format of `SENDER_ID@gcm.googleapis.com`. The `SENDER_ID` should be one of the sender IDs used when calling `getToken(String, String)`
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

IllegalArgumentException |
IOException |

#### public void unregister ()

This method is deprecated.
Instead use `InstanceID.deleteToken()` or `InstanceID.deleteInstanceID()`.

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 all your registration IDs returned from register() or subscribe(). This should not be done unnecessarily. A better approach is to simply have your server stop sending messages.

##### Throws

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