IntentService
+ com.google.android.gcm.GCMBaseIntentService
+This document covers advanced topics for GCM.
+ + + + +When a 3rd-party server posts a message to GCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors.
+In the best-case scenario, if the device is connected to GCM, the screen is on, and there are no throttling restrictions (see Throttling), the message will be delivered right away.
+If the device is connected but idle, the message will still be
+delivered right away unless the delay_while_idle flag is set to true. Otherwise, it will be stored in the GCM servers until the device is awake. And that's where the collapse_key flag plays a role: if there is already a message with the same collapse key (and registration ID) stored and waiting for delivery, the old message will be discarded and the new message will take its place (that is, the old message will be collapsed by the new one). However, if the collapse key is not set, both the new and old messages are stored for future delivery.
Note: There is a limit on how many messages can be stored without collapsing. That limit is currently 100. If the limit is reached, all stored messages are discarded. Then when the device is back online, it receives a special message indicating that the limit was reached. The application can then handle the situation properly, typically by requesting a full sync.
+ +If the device is not connected to GCM, the message will be stored until a connection is established (again respecting the collapse key rules). When a connection is established, GCM will deliver all pending messages to the device, regardless of the delay_while_idle flag. If the device never gets connected again (for instance, if it was factory reset), the message will eventually time out and be discarded from GCM storage. The default timeout is 4 weeks, unless the time_to_live flag is set.
Note: When you set the time_to_live flag, you must also set collapse_key. Otherwise the message will be rejected as a bad request.
Finally, when GCM attempts to deliver a message to the device and the application was uninstalled, GCM will discard that message right away and invalidate the registration ID. Future attempts to send a message to that device will get a NotRegistered error. See How Unregistration Works for more information.
Although is not possible to track the status of each individual message, the Google APIs Console stats are broken down by messages sent to device, messages collapsed, and messages waiting for delivery.
+ +To prevent abuse (such as sending a flood of messages to a device) and +to optimize for the overall network efficiency and battery life of +devices, GCM implements throttling of messages using a token bucket +scheme. Messages are throttled on a per application and per collapse +key basis (including non-collapsible messages). Each application +collapse key is granted some initial tokens, and new tokens are granted +periodically therefter. Each token is valid for a single message sent to +the device. If an application collapse key exhausts its supply of +available tokens, new messages are buffered in a pending queue until +new tokens become available at the time of the periodic grant. Thus +throttling in between periodic grant intervals may add to the latency +of message delivery for an application collapse key that sends a large +number of messages within a short period of time. Messages in the pending +queue of an application collapse key may be delivered before the time +of the next periodic grant, if they are piggybacked with messages +belonging to a non-throttled category by GCM for network and battery +efficiency reasons.
+ +Whenever the application receives a com.google.android.c2dm.intent.REGISTRATION intent with a registration_id extra, it should save the ID for future use, pass it to the 3rd-party server to complete the registration, and keep track of whether the server completed the registration. If the server fails to complete the registration, it should try again or unregister from GCM.
There are also two other scenarios that require special care:
+When an application is updated, it should invalidate its existing registration ID, as it is not guaranteed to work with the new version. Because there is no lifecycle method called when the application is updated, the best way to achieve this validation is by storing the current application version when a registration ID is stored. Then when the application is started, compare the stored value with the current application version. If they do not match, invalidate the stored data and start the registration process again.
+ +Similarly, you should not save the registration ID when an application is backed up. This is because the registration ID could become invalid by the time the application is restored, which would put the application in an invalid state (that is, the application thinks it is registered, but the server and GCM do not store that registration ID anymore—thus the application will not get more messages).
+On the server side, as long as the application is behaving well, everything should work normally. However, if a bug in the application triggers multiple registrations for the same device, it can be hard to reconcile state and you might end up with duplicate messages.
+GCM provides a facility called "canonical registration IDs" to easily recover from these situations. A canonical registration ID is defined to be the ID of the last registration requested by your application. This is the ID that the server should use when sending messages to the device.
+If later on you try to send a message using a different registration ID, GCM will process the request as usual, but it will include the canonical registration ID in the registration_id field of the response. Make sure to replace the registration ID stored in your server with this canonical ID, as eventually the ID you're using will stop working.
When the application receives a com.google.android.c2dm.intent.REGISTRATION intent with the error extra set as SERVICE_NOT_AVAILABLE, it should retry the failed operation (register or unregister).
In the simplest case, if your application just calls register and GCM is not a fundamental part of the application, the application could simply ignore the error and try to register again the next time it starts. Otherwise, it should retry the previous operation using exponential back-off. In exponential back-off, each time there is a failure, it should wait twice the previous amount of time before trying again. If the register (or unregister) operation was synchronous, it could be retried in a simple loop. However, since it is asynchronous, the best approach is to schedule a pending intent to retry the operation. The following steps describe how to implement this in the MyIntentService example used above:
private static final String TOKEN = + Long.toBinaryString(new Random().nextLong()); ++ +
handleRegistration() method so it creates the pending intent when appropriate:...
+if (error != null) {
+ if ("SERVICE_NOT_AVAILABLE".equals(error)) {
+ long backoffTimeMs = // get back-off time from shared preferences
+ long nextAttempt = SystemClock.elapsedRealtime() + backoffTimeMs;
+ Intent retryIntent = new Intent("com.example.gcm.intent.RETRY");
+ retryIntent.putExtra("token", TOKEN);
+ PendingIntent retryPendingIntent =
+ PendingIntent.getBroadcast(context, 0, retryIntent, 0);
+ AlarmManager am = (AlarmManager)
+ context.getSystemService(Context.ALARM_SERVICE);
+ am.set(AlarmManager.ELAPSED_REALTIME, nextAttempt, retryPendingIntent);
+ backoffTimeMs *= 2; // Next retry should wait longer.
+ // update back-off time on shared preferences
+ } else {
+ // Unrecoverable error, log it
+ Log.i(TAG, "Received error: " + error);
+}
+...
+The back-off time is stored in a shared preference. This ensures that it is persistent across multiple activity launches. The name of the intent does not matter, as long as the same intent is used in the following steps.
+ +onHandleIntent() method adding an else if case for the retry intent:...
+} else if (action.equals("com.example.gcm.intent.RETRY")) {
+ String token = intent.getStringExtra("token");
+ // make sure intent was generated by this class, not by a malicious app
+ if (TOKEN.equals(token)) {
+ String registrationId = // get from shared properties
+ if (registrationId != null) {
+ // last operation was attempt to unregister; send UNREGISTER intent again
+ } else {
+ // last operation was attempt to register; send REGISTER intent again
+ }
+}
+...
+
+ MyReceiver in your activity:private final MyBroadcastReceiver mRetryReceiver = new MyBroadcastReceiver(); ++ +
onCreate() method, register the new instance to receive the com.example.gcm.intent.RETRY intent:
+ ...
+IntentFilter filter = new IntentFilter("com.example.gcm.intent.RETRY");
+filter.addCategory(getPackageName());
+registerReceiver(mRetryReceiver, filter);
+...
+
+Note: You must dynamically create a new instance of the broadcast receiver since the one defined by the manifest can only receive intents with the com.google.android.c2dm.permission.SEND permission. The permission com.google.android.c2dm.permission.SEND is a system permission and as such it cannot be granted to a regular application.
onDestroy() method, unregister the broadcast receiver:unregisterReceiver(mRetryReceiver);+
There are two ways to unregister a device from GCM: manually and automatically.
+An Android application can manually unregister itself by issuing a com.google.android.c2dm.intent.UNREGISTER intent, which is useful when the application offers a logoff feature (so it can unregister on logoff and register again on logon). See the Architectural Overview for more discussion of this topic. This is the sequence of events when an application unregisters itself:
com.google.android.c2dm.intent.UNREGISTER intent, passing the registration ID (the application should have saved its registration ID when it received the proper com.google.android.c2dm.intent.REGISTRATION intent).com.google.android.c2dm.intent.REGISTRATION intent with the unregistered extra set.An application can be automatically unregistered after it is uninstalled from the device. However, this process does not happens right away, as Android does not provide an uninstall callback. What happens in this scenario is as follows:
+NotRegistered error message to the 3rd-party server.Note that it might take a while for the registration ID be completely removed from GCM. Thus it is possible that messages sent during step 7 above gets a valid message ID as response, even though the message will not be delivered to the device. Eventually, the registration ID will be removed and the server will get a NotRegistered error, without any further action being required from the 3rd-party server (this scenario happens frequently while an application is being developed and tested).
Every message sent in GCM, regardless of its other characteristics, is either a "send-to-sync" (collapsible) message or a "message with payload" (non-collapsible message).
+A send-to-sync (collapsible) message is typically a "tickle" that tells a mobile application to sync data from the server. For example, suppose you have an email application. When a user receives new email on the server, the server pings the mobile application with a "New mail" message. This tells the application to sync to the server to pick up the new email. The server might send this message multiple times as new mail continues to accumulate, before the application has had a chance to sync. But if the user has received 25 new emails, there's no need to preserve every "New mail" message. One is sufficient. This is a case where you would use the GCM collapse_key parameter. A collapse key is an arbitrary string that is used to collapse a group of like messages when the device is offline, so that only the last message gets sent to the client. For example, "New mail," "Updates available," and so on
GCM allows a maximum of 4 different collapse keys to be used by the GCM server at any given time. In other words, the GCM server can simultaneously store 4 different send-to-sync messages, each with a different collapse key.
+Unlike a send-to-sync message, every "message with payload" (non-collapsible message) is delivered. The payload the message contains can be up to 4K. For example, here is a JSON-formatted message in an IM application in which spectators are discussing a sporting event:
+ +{
+ "registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
+ "data" : {
+ "Nick" : "Mario",
+ "Text" : "great match!",
+ "Room" : "PortugalVSDenmark",
+ },
+}
+
+A "message with payload" is not simply a "ping" to the mobile application to contact the server to fetch data. In the aforementioned IM application, for example, you would want to deliver every message, because every message has different content. To specify a non-collapsible message, you simply omit the collapse_key parameter. Thus GCM will send each message individually. Note that the order of delivery is not guaranteed.
GCM will store up to 100 non-collapsible messages. After that, all messages are discarded from GCM, and a new message is created that tells the client how far behind it is. The message is delivered through a regular com.google.android.c2dm.intent.RECEIVE intent, with the following extras:
message_type—The value is always the string "deleted_messages".total_deleted—The value is a string with the number of deleted messages.The application should respond by syncing with the server to recover the discarded messages.
+Note: If your application does not need to use non-collapsible messages, collapsible messages are a better choice from a performance standpoint, because they put less of a burden on the device battery. + +
+The Time to Live (TTL) feature lets the sender specify the maximum lifespan of a message using the time_to_live parameter in the send request. The value of this parameter must be a duration from 0 to 2,419,200 seconds, and it corresponds to the maximum period of time for which GCM will store and try to deliver the message. Requests that don't contain this field default to the maximum period of 4 weeks.
Here are some possible uses for this feature:
+GCM will usually deliver messages immediately after they are sent. However, this might not always be possible. For example, the device could be turned off, offline, or otherwise unavailable. In other cases, the sender itself might request that messages not be delivered until the device becomes active by using the delay_while_idle flag. Finally, GCM might intentionally delay messages to prevent an application from consuming excessive resources and negatively impacting battery life.
When this happens, GCM will store the message and deliver it as soon as it's feasible. While this is fine in most cases, there are some applications for which a late message might as well never be delivered. For example, if the message is an incoming call or video chat notification, it will only be meaningful for a small period of time before the call is terminated. Or if the message is an invitation to an event, it will be useless if received after the event has ended.
+Another advantage of specifying the expiration date for a message is that GCM will never throttle messages with a time_to_live value of 0 seconds. In other words, GCM will guarantee best effort for messages that must be delivered "now or never." Keep in mind that a time_to_live value of 0 means messages that can't be delivered immediately will be discarded. However, because such messages are never stored, this provides the best latency for sending notifications.
Here is an example of a JSON-formatted request that includes TTL:
+
+{
+ "collapse_key" : "demo",
+ "delay_while_idle" : true,
+ "registration_ids" : ["xyz"],
+ "data" : {
+ "key1" : "value1",
+ "key2" : "value2",
+ },
+ "time_to_live" : 3
+},
+
+
+
+GCM allows multiple parties to send messages to the same application. For example, suppose your application is an articles aggregator with multiple contributors, and you want each of them to be able to send a message when they publish a new article. This message might contain a URL so that the application can download the article. Instead of having to centralize all sending activity in one location, GCM gives you the ability to let each of these contributors send its own messages.
+To make this possible, all you need to do is have each sender generate its own project ID. Then include those IDs in the sender field, separated by commas, when requesting a registration. Finally, share the registration ID with your partners, and they'll be able to send messages to your application using their own authentication keys.
+This code snippet illustrates this feature. Senders are passed as an intent extra in a comma-separated list:
+Intent intent = new Intent(GCMConstants.INTENT_TO_GCM_REGISTRATION); +intent.setPackage(GSF_PACKAGE); +intent.putExtra(GCMConstants.EXTRA_APPLICATION_PENDING_INTENT, + PendingIntent.getBroadcast(context, 0, new Intent(), 0)); +String senderIds = "968350041068,652183961211"; +intent.putExtra(GCMConstants.EXTRA_SENDER, senderIds); +ontext.startService(intent); ++ +
Note that there is limit of 100 multiple senders.
+ diff --git a/docs/html/guide/google/gcm/c2dm.jd b/docs/html/guide/google/gcm/c2dm.jd new file mode 100644 index 0000000000000..fd1bb0c5a6dff --- /dev/null +++ b/docs/html/guide/google/gcm/c2dm.jd @@ -0,0 +1,107 @@ +page.title=Migration +@jd:body + +Android Cloud to Device Messaging (C2DM) is deprecated. The C2DM service will continue to be maintained in the short term, but C2DM will accept no new users, and it will grant no new quotas. C2DM developers are strongly encouraged to move to Google Cloud Messaging (GCM). GCM is the next generation of C2DM.
+This document is addressed to C2DM developers who are moving to GCM. It describes the differences between GCM and C2DM, and explains how to migrate existing C2DM apps to GCM.
+ + +C2DM was launched in 2010 to help Android apps send data from servers to their applications. Servers can tell apps to contact the server directly, to fetch updated application or user data. The C2DM service handles all aspects of queueing of messages and delivery to the target application running on the target device.
+GCM replaces C2DM. The focus of GCM is as follows:
+GCM builds on the core foundation of C2DM. Here is what's different:
+ +collapse_key parameter and messages will not be collapsed. GCM will store up to 100 messages. If you exceed that number, all messages will be discarded but you will receive a special message. If an application receives this message, it needs to sync with the server. For more information, see Advanced Topics.GCM also provides helper libraries (client and server) to make writing your code easier.
+This section describes how to move existing C2DM apps to GCM.
+Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project ID generated when signing up for the new service. For example:
+Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER");
+// sets the app name in the intent
+registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0));
+registrationIntent.putExtra("sender", senderID);
+startService(registrationIntent);
+After receiving a response from GCM, the registration ID obtained must be sent to the application server. When doing this, the application should indicate that it is sending a GCM registration ID so that the server can distinguish it from existing C2DM registrations.
+When the application server receives a GCM registration ID, it should store it and mark it as such.
+Sending messages to GCM devices requires a few changes:
+https://android.googleapis.com/gcm/send.For example: +
+Content-Type:application/json
+Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA
+
+{
+ "registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
+ "data" : {
+ "Team" : "Portugal",
+ "Score" : "3",
+ "Player" : "Varela",
+ },
+}
+For a detailed discussion of this topic and more examples, see the Architectural Overview.
+Eventually, once enough users of your application have migrated to the new service, you might want to take advantage of the new JSON-formatted requests that give access to the full set of features provided by GCM.
+ diff --git a/docs/html/guide/google/gcm/client-javadoc/allclasses-frame.html b/docs/html/guide/google/gcm/client-javadoc/allclasses-frame.html new file mode 100644 index 0000000000000..4788142af7689 --- /dev/null +++ b/docs/html/guide/google/gcm/client-javadoc/allclasses-frame.html @@ -0,0 +1,37 @@ + + + + + +| GCMBaseIntentService
+ +GCMBroadcastReceiver + +GCMConstants + +GCMRegistrar + + |
+
| GCMBaseIntentService
+ +GCMBroadcastReceiver + +GCMConstants + +GCMRegistrar + + |
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public abstract class GCMBaseIntentService
+Skeleton for application-specific IntentServices responsible for
+ handling communication from Google Cloud Messaging service.
+
+ The abstract methods in this class are called from its worker thread, and + hence should run in a limited amount of time. If they execute long + operations, they should spawn new threads, otherwise the worker thread will + be blocked. +
+ +
+
| +Field Summary | +|
|---|---|
+static java.lang.String |
+TAG
+
++ |
+
| +Constructor Summary | +|
|---|---|
+protected |
+GCMBaseIntentService(java.lang.String senderId)
+
++ Subclasses must create a public no-arg constructor and pass the + sender id to be used for registration. |
+
| +Method Summary | +|
|---|---|
+protected void |
+onDeletedMessages(Context context,
+ int total)
+
++ Called when the GCM server tells pending messages have been deleted + because the device was idle. |
+
+protected abstract void |
+onError(Context context,
+ java.lang.String errorId)
+
++ Called on registration or unregistration error. |
+
+ void |
+onHandleIntent(Intent intent)
+
++ |
+
+protected abstract void |
+onMessage(Context context,
+ Intent intent)
+
++ Called when a cloud message has been received. |
+
+protected boolean |
+onRecoverableError(Context context,
+ java.lang.String errorId)
+
++ Called on a registration error that could be retried. |
+
+protected abstract void |
+onRegistered(Context context,
+ java.lang.String registrationId)
+
++ Called after a device has been registered. |
+
+protected abstract void |
+onUnregistered(Context context,
+ java.lang.String registrationId)
+
++ Called after a device has been unregistered. |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Field Detail | +
|---|
+public static final java.lang.String TAG+
| +Constructor Detail | +
|---|
+protected GCMBaseIntentService(java.lang.String senderId)+
+
| +Method Detail | +
|---|
+protected abstract void onMessage(Context context, + Intent intent)+
+
context - application's context.intent - intent containing the message payload as extras.+protected void onDeletedMessages(Context context, + int total)+
+
context - application's context.total - total number of collapsed messages+protected boolean onRecoverableError(Context context, + java.lang.String errorId)+
By default, it does nothing and returns true, but could be + overridden to change that behavior and/or display the error. +
+
context - application's context.errorId - error id returned by the GCM service.
++protected abstract void onError(Context context, + java.lang.String errorId)+
+
context - application's context.errorId - error id returned by the GCM service.+protected abstract void onRegistered(Context context, + java.lang.String registrationId)+
+
context - application's context.registrationId - the registration id returned by the GCM service.+protected abstract void onUnregistered(Context context, + java.lang.String registrationId)+
+
registrationId - the registration id that was previously registered.context - application's context.+public final void onHandleIntent(Intent intent)+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public class GCMBroadcastReceiver
+BroadcastReceiver that receives GCM messages and delivers them to
+ an application-specific GCMBaseIntentService subclass.
+
+ By default, the GCMBaseIntentService class belongs to the application
+ main package and is named
+ GCMConstants.DEFAULT_INTENT_SERVICE_CLASS_NAME. To use a new class,
+ the getGCMIntentServiceClassName(Context) must be overridden.
+
+ +
+
| +Constructor Summary | +|
|---|---|
GCMBroadcastReceiver()
+
++ |
+|
| +Method Summary | +|
|---|---|
+protected java.lang.String |
+getGCMIntentServiceClassName(Context context)
+
++ Gets the class name of the intent service that will handle GCM messages. |
+
+ void |
+onReceive(Context context,
+ Intent intent)
+
++ |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Constructor Detail | +
|---|
+public GCMBroadcastReceiver()+
| +Method Detail | +
|---|
+public final void onReceive(Context context, + Intent intent)+
+protected java.lang.String getGCMIntentServiceClassName(Context context)+
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class GCMConstants
+Constants used by the GCM library. +
+ +
+
| +Field Summary | +|
|---|---|
+static java.lang.String |
+DEFAULT_INTENT_SERVICE_CLASS_NAME
+
++ |
+
+static java.lang.String |
+ERROR_ACCOUNT_MISSING
+
++ There is no Google account on the phone. |
+
+static java.lang.String |
+ERROR_AUTHENTICATION_FAILED
+
++ Bad password. |
+
+static java.lang.String |
+ERROR_INVALID_PARAMETERS
+
++ The request sent by the phone does not contain the expected parameters. |
+
+static java.lang.String |
+ERROR_INVALID_SENDER
+
++ The sender account is not recognized. |
+
+static java.lang.String |
+ERROR_PHONE_REGISTRATION_ERROR
+
++ Incorrect phone registration with Google. |
+
+static java.lang.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. |
+
+static java.lang.String |
+EXTRA_APPLICATION_PENDING_INTENT
+
++ Extra used on INTENT_TO_GCM_REGISTRATION to get the application
+ id. |
+
+static java.lang.String |
+EXTRA_ERROR
+
++ Extra used on INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ an error when the registration fails. |
+
+static java.lang.String |
+EXTRA_REGISTRATION_ID
+
++ Extra used on INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ the registration id when the registration succeeds. |
+
+static java.lang.String |
+EXTRA_SENDER
+
++ Extra used on INTENT_TO_GCM_REGISTRATION to indicate the sender
+ account (a Google email) that owns the application. |
+
+static java.lang.String |
+EXTRA_SPECIAL_MESSAGE
+
++ Type of message present in the INTENT_FROM_GCM_MESSAGE intent. |
+
+static java.lang.String |
+EXTRA_TOTAL_DELETED
+
++ Number of messages deleted by the server because the device was idle. |
+
+static java.lang.String |
+EXTRA_UNREGISTERED
+
++ Extra used on INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ that the application has been unregistered. |
+
+static java.lang.String |
+INTENT_FROM_GCM_LIBRARY_RETRY
+
++ Intent used by the GCM library to indicate that the registration call + should be retried. |
+
+static java.lang.String |
+INTENT_FROM_GCM_MESSAGE
+
++ Intent sent by GCM containing a message. |
+
+static java.lang.String |
+INTENT_FROM_GCM_REGISTRATION_CALLBACK
+
++ Intent sent by GCM indicating with the result of a registration request. |
+
+static java.lang.String |
+INTENT_TO_GCM_REGISTRATION
+
++ Intent sent to GCM to register the application. |
+
+static java.lang.String |
+INTENT_TO_GCM_UNREGISTRATION
+
++ Intent sent to GCM to unregister the application. |
+
+static java.lang.String |
+PERMISSION_GCM_INTENTS
+
++ Permission necessary to receive GCM intents. |
+
+static java.lang.String |
+VALUE_DELETED_MESSAGES
+
++ Special message indicating the server deleted the pending messages. |
+
| +Method Summary | +
|---|
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Field Detail | +
|---|
+public static final java.lang.String INTENT_TO_GCM_REGISTRATION+
+
+public static final java.lang.String INTENT_TO_GCM_UNREGISTRATION+
+
+public static final java.lang.String INTENT_FROM_GCM_REGISTRATION_CALLBACK+
+
+public static final java.lang.String INTENT_FROM_GCM_LIBRARY_RETRY+
+
+public static final java.lang.String INTENT_FROM_GCM_MESSAGE+
+
+public static final java.lang.String EXTRA_SENDER+
INTENT_TO_GCM_REGISTRATION to indicate the sender
+ account (a Google email) that owns the application.
++
+public static final java.lang.String EXTRA_APPLICATION_PENDING_INTENT+
INTENT_TO_GCM_REGISTRATION to get the application
+ id.
++
+public static final java.lang.String EXTRA_UNREGISTERED+
INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ that the application has been unregistered.
++
+public static final java.lang.String EXTRA_ERROR+
INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ an error when the registration fails. See constants starting with ERROR_
+ for possible values.
++
+public static final java.lang.String EXTRA_REGISTRATION_ID+
INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ the registration id when the registration succeeds.
++
+public static final java.lang.String EXTRA_SPECIAL_MESSAGE+
INTENT_FROM_GCM_MESSAGE intent.
+ This extra is only set for special messages sent from GCM, not for
+ messages originated from the application.
++
+public static final java.lang.String VALUE_DELETED_MESSAGES+
+
+public static final java.lang.String EXTRA_TOTAL_DELETED+
VALUE_DELETED_MESSAGES
++
+public static final java.lang.String PERMISSION_GCM_INTENTS+
+
+public static final java.lang.String DEFAULT_INTENT_SERVICE_CLASS_NAME+
GCMBroadcastReceiver,
+Constant Field Values+public static final java.lang.String ERROR_SERVICE_NOT_AVAILABLE+
+
+public static final java.lang.String ERROR_ACCOUNT_MISSING+
+
+public static final java.lang.String ERROR_AUTHENTICATION_FAILED+
+
+public static final java.lang.String ERROR_INVALID_PARAMETERS+
+
+public static final java.lang.String ERROR_INVALID_SENDER+
+
+public static final java.lang.String ERROR_PHONE_REGISTRATION_ERROR+
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class GCMRegistrar
+Utilities for device registration. +
+ Note: this class uses a private SharedPreferences
+ object to keep track of the registration token.
+
+ +
+
| +Method Summary | +|
|---|---|
+static void |
+checkDevice(Context context)
+
++ Checks if the device has the proper dependencies installed. |
+
+static void |
+checkManifest(Context context)
+
++ Checks that the application manifest is properly configured. |
+
+static java.lang.String |
+getRegistrationId(Context context)
+
++ Gets the current registration id for application on GCM service. |
+
+static boolean |
+isRegistered(Context context)
+
++ Checks whether the application was successfully registered on GCM + service. |
+
+static boolean |
+isRegisteredOnServer(Context context)
+
++ Checks whether the device was successfully registered in the server side. |
+
+static void |
+onDestroy(Context context)
+
++ Clear internal resources. |
+
+static void |
+register(Context context,
+ java.lang.String... senderIds)
+
++ Initiate messaging registration for the current application. |
+
+static void |
+setRegisteredOnServer(Context context,
+ boolean flag)
+
++ Sets whether the device was successfully registered in the server side. |
+
+static void |
+unregister(Context context)
+
++ Unregister the application. |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Method Detail | +
|---|
+public static void checkDevice(Context context)+
+ This method should be called when the application starts to verify that + the device supports GCM. +
+
context - application context.
+java.lang.UnsupportedOperationException - if the device does not support GCM.+public static void checkManifest(Context context)+
+ A proper configuration means: +
PACKAGE_NAME.permission.C2D_MESSAGE.
+ BroadcastReceiver with category
+ PACKAGE_NAME.
+ BroadcastReceiver(s) uses the
+ permission.
+ BroadcastReceiver(s) handles the 3 GCM intents
+ (,
+ ,
+ and ).
+ PACKAGE_NAME is the application package.
+ + This method should be used during development time to verify that the + manifest is properly set up, but it doesn't need to be called once the + application is deployed to the users' devices. +
+
context - application context.
+java.lang.IllegalStateException - if any of the conditions above is not met.+public static void register(Context context, + java.lang.String... senderIds)+
+ The result will be returned as an
+ GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK intent with
+ either a GCMConstants.EXTRA_REGISTRATION_ID or
+ GCMConstants.EXTRA_ERROR.
+
+
context - application context.senderIds - Google Project ID of the accounts authorized to send
+ messages to this application.
+java.lang.IllegalStateException - if device does not have all GCM
+ dependencies installed.+public static void unregister(Context context)+
+ The result will be returned as an
+ GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK intent with an
+ GCMConstants.EXTRA_UNREGISTERED extra.
+
+
+public static void onDestroy(Context context)+
+ This method should be called by the main activity's onDestroy()
+ method.
+
+
+public static java.lang.String getRegistrationId(Context context)+
+ If result is empty, the registration has failed. +
+
+public static boolean isRegistered(Context context)+
+
+public static void setRegisteredOnServer(Context context, + boolean flag)+
+
+public static boolean isRegisteredOnServer(Context context)+
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
|
+Classes
+
+ +GCMBaseIntentService + +GCMBroadcastReceiver + +GCMConstants + +GCMRegistrar |
+
+
+
|
++ + | +|||||||
| + PREV PACKAGE + NEXT PACKAGE | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| +Class Summary | +|
|---|---|
| GCMBaseIntentService | +Skeleton for application-specific IntentServices responsible for
+ handling communication from Google Cloud Messaging service. |
+
| GCMBroadcastReceiver | +BroadcastReceiver that receives GCM messages and delivers them to
+ an application-specific GCMBaseIntentService subclass. |
+
| GCMConstants | +Constants used by the GCM library. | +
| GCMRegistrar | +Utilities for device registration. | +
+
+
+
|
++ + | +|||||||
| + PREV PACKAGE + NEXT PACKAGE | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| +com.google.* | +
|---|
+ +
| com.google.android.gcm.GCMBaseIntentService | +||
|---|---|---|
+public static final java.lang.String |
+TAG |
+"GCMBaseIntentService" |
+
+ +
+ +
| com.google.android.gcm.GCMConstants | +||
|---|---|---|
+public static final java.lang.String |
+DEFAULT_INTENT_SERVICE_CLASS_NAME |
+".GCMIntentService" |
+
+public static final java.lang.String |
+ERROR_ACCOUNT_MISSING |
+"ACCOUNT_MISSING" |
+
+public static final java.lang.String |
+ERROR_AUTHENTICATION_FAILED |
+"AUTHENTICATION_FAILED" |
+
+public static final java.lang.String |
+ERROR_INVALID_PARAMETERS |
+"INVALID_PARAMETERS" |
+
+public static final java.lang.String |
+ERROR_INVALID_SENDER |
+"INVALID_SENDER" |
+
+public static final java.lang.String |
+ERROR_PHONE_REGISTRATION_ERROR |
+"PHONE_REGISTRATION_ERROR" |
+
+public static final java.lang.String |
+ERROR_SERVICE_NOT_AVAILABLE |
+"SERVICE_NOT_AVAILABLE" |
+
+public static final java.lang.String |
+EXTRA_APPLICATION_PENDING_INTENT |
+"app" |
+
+public static final java.lang.String |
+EXTRA_ERROR |
+"error" |
+
+public static final java.lang.String |
+EXTRA_REGISTRATION_ID |
+"registration_id" |
+
+public static final java.lang.String |
+EXTRA_SENDER |
+"sender" |
+
+public static final java.lang.String |
+EXTRA_SPECIAL_MESSAGE |
+"message_type" |
+
+public static final java.lang.String |
+EXTRA_TOTAL_DELETED |
+"total_deleted" |
+
+public static final java.lang.String |
+EXTRA_UNREGISTERED |
+"unregistered" |
+
+public static final java.lang.String |
+INTENT_FROM_GCM_LIBRARY_RETRY |
+"com.google.android.gcm.intent.RETRY" |
+
+public static final java.lang.String |
+INTENT_FROM_GCM_MESSAGE |
+"com.google.android.c2dm.intent.RECEIVE" |
+
+public static final java.lang.String |
+INTENT_FROM_GCM_REGISTRATION_CALLBACK |
+"com.google.android.c2dm.intent.REGISTRATION" |
+
+public static final java.lang.String |
+INTENT_TO_GCM_REGISTRATION |
+"com.google.android.c2dm.intent.REGISTER" |
+
+public static final java.lang.String |
+INTENT_TO_GCM_UNREGISTRATION |
+"com.google.android.c2dm.intent.UNREGISTER" |
+
+public static final java.lang.String |
+PERMISSION_GCM_INTENTS |
+"com.google.android.c2dm.permission.SEND" |
+
+public static final java.lang.String |
+VALUE_DELETED_MESSAGES |
+"deleted_messages" |
+
+ +
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+ +++Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
+- Interfaces (italic)
- Classes
- Enums
- Exceptions
- Errors
- Annotation Types
+ ++ ++Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.- Class inheritance diagram
- Direct Subclasses
- All Known Subinterfaces
- All Known Implementing Classes
- Class/interface declaration
- Class/interface description +
+
- Nested Class Summary
- Field Summary
- Constructor Summary
- Method Summary +
+
- Field Detail
- Constructor Detail
- Method Detail
+ ++ ++Each annotation type has its own separate page with the following sections:
+
+- Annotation Type declaration
- Annotation Type description
- Required Element Summary
- Optional Element Summary
- Element Detail
+ +++Each enum has its own separate page with the following sections:
+
+- Enum declaration
- Enum description
- Enum Constant Summary
- Enum Constant Detail
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with+java.lang.Object. The interfaces do not inherit fromjava.lang.Object.+
+- When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
- When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.+
+
+
+
+
+This help file applies to API documentation generated using the standard doclet.
+
+
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
GCMConstants.INTENT_TO_GCM_REGISTRATION to get the application
+ id.
+GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ an error when the registration fails.
+GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ the registration id when the registration succeeds.
+GCMConstants.INTENT_TO_GCM_REGISTRATION to indicate the sender
+ account (a Google email) that owns the application.
+GCMConstants.INTENT_FROM_GCM_MESSAGE intent.
+GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK to indicate
+ that the application has been unregistered.
+IntentServices responsible for
+ handling communication from Google Cloud Messaging service.BroadcastReceiver that receives GCM messages and delivers them to
+ an application-specific GCMBaseIntentService subclass.
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
The Google Cloud Messaging (GCM) Demo demonstrates how to use the Google Cloud Messaging framework in your Android application. This tutorial walks you through setting up and running the demo.
+ + +This demo consists of the following pieces:
+Here is the API reference documentation for the helper libraries on which the demo is based:
+ +For the web server:
+For the Android application:
+Before proceeding with the server and client setup, it's necessary to register a Google account with the Google API Console, enable Google Cloud Messaging in GCM, and obtain an API key from the Google API Console.
+For instructions on how to set up GCM, see Getting Started.
+ + +This section describes the different options for setting up a server.
+To set up the server using a standard, servlet-compliant web server:
+This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.
gcm-demo-server/WebContent/WEB-INF/classes/api.key and replace the existing text with the API key obtained above.gcm-demo-server directory.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 ++ +
dist/gcm-demo.war to your running server. For instance, if you're using Jetty, copy gcm-demo.war to the webapps directory of the Jetty installation.http://192.168.1.10:8080/gcm-demo/home, where gcm-demo is the application context and /home is the path of the main servlet.
+
+ Note: You can get the IP by running ifconfig on Linux or MacOS, or ipconfig on Windows.
You server is now ready.
+To set up the server using a standard App Engine for Java:
+This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.
gcm-demo-appengine/src/com/google/android/gcm/demo/server/ApiKeyInitializer.java and replace the existing text with the API key obtained above.
+ Note: The API key value set in that class will be used just once to create a persistent entity on App Engine. If you deploy the application, you can use App Engine's Datastore Viewer to change it later.
gcm-api-server directory.ant runserver, using the -Dsdk.dir to indicate the location of the App Engine SDK and -Dserver.host to set your server's hostname or IP address:+$ ant -Dsdk.dir=/opt/google/appengine-java-sdk runserver -Dserver.host=192.168.1.10 +Buildfile: gcm-demo-appengine/build.xml + +init: + [mkdir] Created dir: gcm-demo-appengine/dist + +copyjars: + +compile: + +datanucleusenhance: + [enhance] DataNucleus Enhancer (version 1.1.4) : Enhancement of classes + [enhance] DataNucleus Enhancer completed with success for 0 classes. Timings : input=28 ms, enhance=0 ms, total=28 ms. Consult the log for full details + [enhance] DataNucleus Enhancer completed and no classes were enhanced. Consult the log for full details + +runserver: + [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.jetty.JettyLogger info + [java] INFO: Logging to JettyLogger(null) via com.google.apphosting.utils.jetty.JettyLogger + [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AppEngineWebXmlReader readAppEngineWebXml + [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/appengine-web.xml + [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AbstractConfigXmlReader readConfigXml + [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/web.xml + [java] Jun 15, 2012 8:46:09 PM com.google.android.gcm.demo.server.ApiKeyInitializer contextInitialized + [java] SEVERE: Created fake key. Please go to App Engine admin console, change its value to your API Key (the entity type is 'Settings' and its field to be changed is 'ApiKey'), then restart the server! + [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start + [java] INFO: The server is running at http://192.168.1.10:8080/ + [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start + [java] INFO: The admin console is running at http://192.168.1.10:8080/_ah/admin ++ +
http://192.168.1.10:8080/home, where /home is the path of the main servlet.Note: You can get the IP by running ifconfig on Linux or MacOS, or ipconfig on Windows.
You server is now ready.
+To set up the device:
+This creates a gcm directory under YOUR_SDK_ROOT/extras/google containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, gcm-server, and source.properties.
gcm-demo-client/src/com/google/android/gcm/demo/app/CommonUtilities.java and set the proper values for the SENDER_ID and SERVER_URL constants. For example:+static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo"; +static final String SENDER_ID = "4815162342";+
Note that the SERVER_URL is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (/). Also note that SENDER_ID is the Google API project ID you obtained in the server setup steps above.
gcm-demo-client directory.android tool to generate the ant build files:+$ android update project --name GCMDemo -p . --target android-16 +Updated project.properties +Updated local.properties +Updated file ./build.xml +Updated file ./proguard-project.txt ++
If this command fails becase android-16 is not recognized, try a different target (as long as it is at least android-15).
ant to build the application's APK file:+$ ant clean debug +Buildfile: build.xml + +... + + +-do-debug: +[zipalign] Running zip align on final apk... + [echo] Debug Package: bin/GCMDemo-debug.apk +[propertyfile] Creating new property file: bin/build.prop +[propertyfile] Updating property file: bin/build.prop +[propertyfile] Updating property file: bin/build.prop +[propertyfile] Updating property file: bin/build.prop + +-post-build: + +debug: + +BUILD SUCCESSFUL +Total time: 3 seconds ++ +
$emulator -avd my_avd ++ +
This example assumes there is an AVD (Android Virtual Device) named my_avd previously configured with Android 2.2 and Google APIs level 8. For more information on how to run an Android emulator, see Managing Virtual Devices in the Android Developers Guide.
senderId) in particular. If the emulator is running Android 4.0.4 or later, this step is optional as GCM does not require an account from this version on.
+ ++$ ant installd +Buildfile: gcm-demo-client/build.xml + +-set-mode-check: + +-set-debug-files: + +install: + [echo] Installing gcm-demo-client/bin/GCMDemo-debug.apk onto default emulator or device... + [exec] 1719 KB/s (47158 bytes in 0.026s) + [exec] pkg: /data/local/tmp/GCMDemo-debug.apk + [exec] Success + +installd: + +BUILD SUCCESSFUL +Total time: 3 seconds ++
Note: What happened? When the device received a registration callback intent from GCM, it contacted the server to register itself, using the register servlet and passing the registration ID received from GCM; the server then saved the registration ID to use it to send messages to the phone.
+
And in your emulator:
+ +
Note: What happened? When you clicked the button, the web server sent a message to GCM addressed to your device (more specifically, to the registration ID returned by GCM during the registration step). The device then received the message and displayed in the main activity; it also issued a system notification so the user would be notified even if the demo application was not running.
+Google Cloud Messaging for Android (GCM) is a service that helps +developers send data from servers to their Android applications on Android devices. This could be a lightweight message telling the Android application that there is new data to be fetched from the server (for instance, a movie uploaded by a friend), or it could be a message containing up to 4kb of payload data (so apps like instant messaging can consume the message directly). The GCM service handles all aspects of queueing of + messages and delivery to the target Android application running on the target + device.
+To jump right into using GCM with your Android + applications, see the instructions in Getting Started.
+ + + + +Here are the primary characteristics of Google Cloud +Messaging (GCM):
+ +This section gives an overview of how GCM works.
+This table summarizes the key terms and concepts involved in GCM. It is +divided into these categories:
+| Components | +|
|---|---|
| Mobile Device | +The device that is running an Android application that uses +GCM. This must be a 2.2 Android device that has Google Play Store installed, and it must +have at least one logged in Google account if the device is running a version lower than Android 4.0.4. Alternatively, for testing you can use an emulator running Android 2.2 with Google APIs. | +
| 3rd-party Application Server | +An application server that developers set up as part of implementing +GCM in their applications. The 3rd-party application server sends data to an +Android application on the device via the GCM server. | +
| GCM Servers | +The Google servers involved in taking messages from the 3rd-party +application server and sending them to the device. | +
| Credentials | +|
| Sender ID | +A project ID you acquire from the API console, as described in Getting Started. 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. +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. | +
| Google User Account | +For GCM to work, the mobile device must include at least one Google account if the device is running a version lower than Android 4.0.4. | +
| Sender Auth Token | +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. | +
Here are the primary processes involved in cloud-to-device messaging:
+ +These processes are described in more detail below.
+ +This is the sequence of events that occurs when an Android application +running on a mobile device registers to receive messages:
+ +This registration Intent
+(com.google.android.c2dm.intent.REGISTER) includes the sender ID, and the Android application ID.
Note: Because there is no lifecycle method that is called when the application is run for
+the first time, the registration intent should be sent on onCreate(), but only if the application is not registered yet.
+
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).
+Note that Google may periodically refresh the registration ID, so you should design your Android application
+with the understanding that the com.google.android.c2dm.intent.REGISTRATION intent may be called
+multiple times. Your Android application needs to be able to respond
+accordingly.
The registration ID lasts until the Android application explicitly unregisters +itself, or until Google refreshes the registration ID for your Android application.
+ +Note: When users uninstall an application, it is not automatically unregistered on GCM. It is only unregistered when the GCM server tries to send a message to the device and the device answers that the application is uninstalled. At that point, you server should mark the device as unregistered (the server will receive a NotRegistered error).
+
+Note that it might take a few minutes for the registration ID to be completed removed from the GCM server. So if the 3rd party server sends a message during this time, it will get a valid message ID, even though the message will not be delivered to the device.
+ + +For an application server to send a message to an Android application, the following things must be in +place:
+ +Here is the sequence of events that occurs when the application server sends a +message:
+ +An Android application can unregister GCM if it no longer wants to receive +messages.
+ +This is the sequence of events that occurs when an Android application +installed on a mobile device receives a message:
+ +com.google.android.c2dm.intent.RECEIVE Intent as a set of
+extras.com.google.android.c2dm.intent.RECEIVE Intent by key and processes the data.When mobile device users install Android applications that include GCM, the Google Play Store will inform them that the Android application +includes GCM. They must approve the use of this feature to install the +Android application.
+ +To write Android applications that use GCM, you must have an application +server that can perform the tasks described in Role of the +3rd-party Application Server. This section describes the steps you take to +create a client application that uses GCM.
+ +Remember that there is no user interface associated with GCM. +However you choose to process messages in your Android application is up to you.
+ +There are two primary steps involved in writing a client Android application:
+ +com.google.android.c2dm.intent.RECEIVE and com.google.android.c2dm.intent.REGISTRATION intents.Every Android application must have an AndroidManifest.xml file (with
+precisely that name) in its root directory. The manifest presents essential
+information about the Android application to the Android system, information the
+system must have before it can run any of the Android application's code (for more
+discussion of the manifest file, see the Android Developers Guide. To use the GCM feature, the
+manifest must include the following:
com.google.android.c2dm.permission.RECEIVE permission so the Android application can register and receive messages.android.permission.INTERNET permission so the Android application can send the registration ID to the 3rd party server.android.permission.GET_ACCOUNTS permission as GCM requires a Google account (necessary only if if the device is running a version lower than Android 4.0.4)android.permission.WAKE_LOCK permission so the application can keep the processor from sleeping when a message is received.applicationPackage + ".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.com.google.android.c2dm.intent.RECEIVE and com.google.android.c2dm.intent.REGISTRATION, with the category set
+as applicationPackage. The receiver should require the com.google.android.c2dm.SEND permission, so that only the GCM
+Framework can send a message to it. Note that both registration and the receiving
+of messages are implemented as Intents.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 are excerpts from a manifest that supports GCM:
+ ++<manifest package="com.example.gcm" ...> + + <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" /> + <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> + + <permission android:name="com.example.gcm.permission.C2D_MESSAGE" + android:protectionLevel="signature" /> + <uses-permission android:name="com.example.gcm.permission.C2D_MESSAGE" /> + + <application ...> + <receiver + android:name=".MyBroadcastReceiver" + android:permission="com.google.android.c2dm.permission.SEND" > + <intent-filter> + <action android:name="com.google.android.c2dm.intent.RECEIVE" /> + <action android:name="com.google.android.c2dm.intent.REGISTRATION" /> + <category android:name="com.example.gcm" /> + </intent-filter> + </receiver> + <service android:name=".MyIntentService" /> + </application> + +</manifest> ++
An Android application needs to register with GCM servers before it can receive messages. To register, the application sends an Intent
+(com.google.android.c2dm.intent.REGISTER), with 2 extra parameters:
+
sender is the project ID of the account authorized to send messages
+to the Android application. app is the Android application's ID, set with a PendingIntent to
+allow the registration service to extract Android application information. For example:
+ +Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER");
+// sets the app name in the intent
+registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0));
+registrationIntent.putExtra("sender", senderID);
+startService(registrationIntent);
+
+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.
+ +To unregister from GCM, do the following:
+ +Intent unregIntent = new Intent("com.google.android.c2dm.intent.UNREGISTER");
+unregIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0));
+startService(unregIntent);
+
+
+Similar to the registration request, this intent is sent asynchronously, and the response comes as a com.google.android.c2dm.intent.REGISTRATION intent.
+
+
+
As discussed in Creating the Manifest, 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.
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.
+You may be tempted to spawn a new thread directly, but there are no guarantees that the process will run long enough for the thread to finish the work.
+Thus the recommended way to handle the intents is to delegate them to a service, such as an {@link android.app.IntentService}.
+For example:
+public class MyBroadcastReceiver extends BroadcastReceiver {
+
+ @Override
+ public final void onReceive(Context context, Intent intent) {
+ MyIntentService.runIntentInService(context, intent);
+ setResult(Activity.RESULT_OK, null, null);
+ }
+}
+
+
+Then in MyIntentService:
+public class MyIntentService extends IntentService {
+
+ private static PowerManager.WakeLock sWakeLock;
+ private static final Object LOCK = MyIntentService.class;
+
+ static void runIntentInService(Context context, Intent intent) {
+ synchronized(LOCK) {
+ if (sWakeLock == null) {
+ PowerManager pm = (PowerManager) context.getSystemService(Context.POWER_SERVICE);
+ sWakeLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "my_wakelock");
+ }
+ }
+ sWakeLock.acquire();
+ intent.setClassName(context, MyIntentService.class.getName());
+ context.startService(intent);
+ }
+
+ @Override
+ public final void onHandleIntent(Intent intent) {
+ try {
+ String action = intent.getAction();
+ if (action.equals("com.google.android.c2dm.intent.REGISTRATION")) {
+ handleRegistration(intent);
+ } else if (action.equals("com.google.android.c2dm.intent.RECEIVE")) {
+ handleMessage(intent);
+ }
+ } finally {
+ synchronized(LOCK) {
+ sWakeLock.release();
+ }
+ }
+ }
+}
+
+
+Note: your application must acquire a wake lock before starting the service—otherwise the device could be put to sleep before the service is started.
+ +When a com.google.android.c2dm.intent.REGISTRATION intent is received, it could potentially contain 3 extras: registration_id, error, and unregistered.
+
+
When a registration succeeds, registration_id contains the registration ID and the other extras are not set.
+The application must ensure that the 3rd-party server receives the registration ID. It may do so by saving the registration ID and sending it to the server.
+If the network is down or there are errors, the application should retry sending the registration ID when the network is up again or the next time it starts.
Note: Although the com.google.android.c2dm.intent.REGISTRATION intent is typically received after a request was made by the application,
+Google may periodically refresh the registration ID. So the application must be prepared to handle it at any time.
When an unregistration succeeds, only the unregistered extra is set, and similar to the registration workflow,
+the application must contact the 3rd-party server to remove the registration ID (note that the registration ID is not available in the intent,
+but the application should have saved the registration ID when it got it).
+ +
If the application request (be it register or unregister) fails, the error will be set with an error code, and the other extras will not be set.
+
+Here are the possible error codes:
| Error Code | +Description | +
|---|---|
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 Android application should use exponential back-off and retry. See Advanced Topics for more information. | +
ACCOUNT_MISSING |
+ There is no Google account on the phone. The Android application should ask the +user to open the account manager and add a Google account. Fix on the device +side. | +
AUTHENTICATION_FAILED |
+ Bad Google Account password. The Android application should ask the user to enter his/her Google Account +password, and let the user retry manually later. Fix on the device side. | +
INVALID_SENDER |
+ The sender account is not recognized. This must be fixed on the Android application side. The developer must fix the application to provide the right sender extra in the com.google.android.c2dm.intent.REGISTER intent. |
+
PHONE_REGISTRATION_ERROR |
+ Incorrect phone registration with Google. This +phone doesn't currently support GCM. | +
INVALID_PARAMETERS |
+ The request sent by the phone does not contain the expected parameters. This phone doesn't currently support GCM. | +
Here's an example on how to handle the registration in the MyIntentService example:
+private void handleRegistration(Intent intent) {
+ String registrationId = intent.getStringExtra("registration_id");
+ String error = intent.getStringExtra("error");
+ String unregistered = intent.getStringExtra("unregistered");
+ // registration succeeded
+ if (registrationId != null) {
+ // store registration ID on shared preferences
+ // notify 3rd-party server about the registered ID
+ }
+
+ // unregistration succeeded
+ if (unregistered != null) {
+ // get old registration ID from shared preferences
+ // notify 3rd-party server about the unregistered ID
+ }
+
+ // last operation (registration or unregistration) returned an error;
+ if (error != null) {
+ if ("SERVICE_NOT_AVAILABLE".equals(error)) {
+ // optionally retry using exponential back-off
+ // (see Advanced Topics)
+ } else {
+ // Unrecoverable error, log it
+ Log.i(TAG, "Received error: " + error);
+ }
+ }
+}
+
+The com.google.android.c2dm.intent.RECEIVE intent is used by GCM to
+deliver the messages sent by the 3rd-party server to the application running in the device.
+If the server included key-pair values in the data parameter, they are available as
+extras in this intent, with the keys being the extra names.
+
+
Here is an example, again using the MyIntentReceiver class:
+private void handleMessage(Intent intent) {
+ // server sent 2 key-value pairs, score and time
+ String score = intent.getExtra("score");
+ String time = intent.getExtra("time");
+ // generates a system notification to display the score and time
+}
+
+Here are some guidelines for developing and testing an Android application +that uses the GCM feature:
+ +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. Before you can write client Android applications that use the GCM feature, you must +have an application server that meets the following criteria:
+ +This section describes how the 3rd-party application server sends messages to one or more mobile devices. Note the following:
+Before the 3rd-party application server can send a message to an + Android application, it must have received a registration ID from it.
+To send a message, the application server issues a POST request to https://android.googleapis.com/gcm/send.
A message request is made of 2 parts: HTTP header and HTTP body.
+ +The HTTP header must contain the following headers:
+Authorization: key=YOUR_API_KEYContent-Type: application/json for JSON; application/x-www-form-urlencoded;charset=UTF-8 for plain text.
+ For example: +
+Content-Type:application/json
+Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA
+
+{
+ "registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
+ "data" : {
+ ...
+ },
+}
++
Note: If Content-Type is omitted, the format is assumed to be plain text.
The HTTP body content depends on whether you're using JSON or plain text. For JSON, it must contain a string representing a JSON object with the following fields:
+| Field | +Description | +
|---|---|
registration_ids |
+ A string array with the list of devices (registration IDs) receiving the message. It must contain at least 1 and at most 1000 registration IDs. To send a multicast message, you must use JSON. For sending a single message to a single device, you could use a JSON object with just 1 registration id, or plain text (see below). Required. | +
collapse_key |
+ An arbitrary string (such as "Updates Available") that is used to collapse a group of like messages
+when the device is offline, so that only the last message gets sent to the
+client. This is intended to avoid sending too many messages to the phone when it
+comes back online. Note that since there is no guarantee of the order in which
+messages get sent, the "last" message may not actually be the last
+message sent by the application server. See Advanced Topics for more discussion of this topic. Optional, unless you are using the time_to_live parameter—in that case, you must also specify a collapse_key. |
+
data |
+ A JSON object whose fields represents the key-value pairs of the message's payload data. If present, the payload data it will be
+included in the Intent as application data, with the key being the extra's name. For instance, "data":{"score":"3x1"} would result in an intent extra named score whose value is the string 3x1
+There is no limit on the number of key/value pairs, though there is a limit on the total size of the message. Optional. |
+
delay_while_idle |
+ If included, indicates that the message should not be sent immediately
+if the device is idle. The server will wait for the device to become active, and
+then only the last message for each collapse_key value will be
+sent. Optional. The default value is false, and must be a JSON boolean. |
+
time_to_live |
+ How long (in seconds) the message should be kept on GCM storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as a JSON number). If you use this parameter, you must also specify a collapse_key. |
+
If you are using plain text instead of JSON, the message fields must be set as HTTP parameters sent in the body, and their syntax is slightly different, as described below: +
| Field | +Description | +
|---|---|
registration_id |
+ Must contain the registration ID of the single device receiving the message. Required. | +
collapse_key |
+ Same as JSON (see previous table). Optional. | +
data.<key> |
+ Payload data, expressed as parameters prefixed with data. and suffixed as the key. For instance, a parameter of data.score=3x1 would result in an intent extra named score whose value is the string 3x1. There is no limit on the number of key/value parameters, though there is a limit on the total size of the message. Optional. |
+
delay_while_idle |
+ Should be represented as 1 or true for true, anything else for false. Optional. The default value is false. |
+
time_to_live |
+ Same as JSON (see previous table). Optional. | +
Here is the smallest possible request (a message without any parameters and just one recipient) using JSON:
+{ "registration_ids": [ "42" ] }
+
+ And here the same example using plain text:
+registration_id=42+ +
Here is a message with a payload and 6 recipients:
+{ "data": {
+ "score": "5x1",
+ "time": "15:10"
+ },
+ "registration_ids": ["4", "8", "15", "16", "23", "42"]
+}
+ Here is a message with all optional fields set and 6 recipients:
+{ "collapse_key": "score_update",
+ "time_to_live": 108,
+ "delay_while_idle": true,
+ "data": {
+ "score": "4x8",
+ "time": "15:16.2342"
+ },
+ "registration_ids":["4", "8", "15", "16", "23", "42"]
+}
+ And here is the same message using plain-text format (but just 1 recipient):
+ +collapse_key=score_update&time_to_live=108&delay_while_idle=1&data.score=4x8&data.time=15:16.2342®istration_id=42 ++ +
Note: If your organization has a firewall that restricts the traffic to or from the Internet, you'll need to configure it to allow connectivity with GCM. The ports to open are: 5228, 5229, and 5230. GCM typically only uses 5228, but it sometimes uses 5229 and 5230. +GCM doesn't provide specific IPs. It changes IPs frequently. We recommend against using ACLs but if you must use them, take a broad approach such as the method suggested in this support link. +
+ +There are two possible outcomes when trying to send a message:
+When the messge is processed successfully, the HTTP response has a 200 status and the body contains more information about the status of the message (including possible errors). When the request is rejected, +the HTTP response contains a non-200 status code (such as 400, 401, or 503).
+ +The following table summarizes the statuses that the HTTP response header might contain. Click the troubleshoot link for advice on how to deal with each type of error.
+| Response | +Description | +
|---|---|
| 200 | +Message was processed successfully. The response body will contain more details about the message status, but its format will depend whether the request was JSON or plain text. See Interpreting a success response for more details. | +
| 400 | +Only applies for JSON requests. Indicates that the request could not be parsed as JSON, or it contained invalid fields (for instance, passing a string where a number was expected). The exact failure reason is described in the response and the problem should be addressed before the request can be retried. | +
| 401 | +There was an error authenticating the sender account. Troubleshoot | +
| 500 | +There was an internal error in the GCM server while trying to process the request. Troubleshoot | +
| 503 | +Indicates that the server is temporarily unavailable (i.e., because of timeouts, etc ). Sender must retry later, honoring any Retry-After header
+ included in the response. Application servers must implement exponential back-off. The GCM server took too long to process the request. Troubleshoot |
+
When a JSON request is successful (HTTP status code 200), the response body contains a JSON object with the following fields:
+| Field | +Description | +
|---|---|
multicast_id |
+ Unique ID (number) identifying the multicast message. | +
success |
+ Number of messages that were processed without an error. | +
failure |
+ Number of messages that could not be processed. | +
canonical_ids |
+ Number of results that contain a canonical registration ID. See Advanced Topics for more discussion of this topic. | +
results |
+ Array of objects representing the status of the messages processed. The objects are listed in the same order as the request (i.e., for each registration ID in the request, its result is listed in the same index in the response) and they can have these fields: +
|
+
If the value of failure and canonical_ids is 0, it's not necessary to parse the remainder of the response. Otherwise, we recommend that you iterate through the results field and do the following for each object in that list:
message_id is set, check for registration_id:
+ registration_id is set, replace the original ID with the new value (canonical ID) in your server database. Note that the original ID is not part of the result, so you need to obtain it from the list of registration_ids passed in the request (using the same index).error:
+ Unavailable, you could retry to send it in another request.NotRegistered, you should remove the registration ID from your server database because the application was uninstalled from the device.When a plain-text request is successful (HTTP status code 200), the response body contains 1 or 2 lines in the form of key/value pairs.
+The first line is always available and its content is either id=ID of sent message or Error=GCM error code. The second line, if available,
+has the format of registration_id=canonical ID. The second line is optional, and it can only be sent if the first line is not an error. We recommend handling the plain-text response in a similar way as handling the JSON response:
id, check second line:
+ registration_id, gets its value and replace the registration IDs in your server database.Error:
+ NotRegistered, remove the registration ID from your server database.Unavailable as the error code, they would have returned a 500 HTTP status instead).Here are the recommendations for handling the different types of error that might occur when trying to send a message to a device:
+ +registration_id parameter in a plain text message, or in the registration_ids field in JSON).
+MissingRegistration.com.google.android.c2dm.intent.REGISTRATION intent and that you're not truncating it or adding additional characters.
+InvalidRegistration.MismatchSenderId.com.google.android.c2dm.intent.UNREGISTER intent.NotRegistered.MessageTooBig.Authorization header is the correct API key associated with your project.
+Retry-After header if it's included in the response from the GCM server.error field of a JSON object in the results array is Unavailable.
+This section shows a few examples of responses indicating messages that were processed successfully. See Example requests for the requests these responses are based on.
+Here is a simple case of a JSON message successfully sent to one recipient without canonical IDs in the response:
+{ "multicast_id": 108,
+ "success": 1,
+ "failure": 0,
+ "canonical_ids": 0,
+ "results": [
+ { "message_id": "1:08" }
+ ]
+}
+
+Or if the request was in plain-text format:
+id=1:08 ++ +
Here are JSON results for 6 recipients (IDs 4, 8, 15, 16, 23, and 42 respectively) with 3 messages successfully processed, 1 canonical registration ID returned, and 3 errors:
+{ "multicast_id": 216,
+ "success": 3,
+ "failure": 3,
+ "canonical_ids": 1,
+ "results": [
+ { "message_id": "1:0408" },
+ { "error": "Unavailable" },
+ { "error": "InvalidRegistration" },
+ { "message_id": "1:1516" },
+ { "message_id": "1:2342", "registration_id": "32" },
+ { "error": "NotRegistered"}
+ ]
+}
+
+In this example:
+Or if just the 4th message above was sent using plain-text format:
+Error=InvalidRegistration ++
If the 5th message above was also sent using plain-text format:
+id=1:2342 +registration_id=32 ++ + +
To view statistics and any error messages for your GCM applications:
+play.google.com/apps/publish.You will see a page that has a list of all of your apps.
Now you are on the statistics page.
See the GCM Demo Application document.
+ diff --git a/docs/html/guide/google/gcm/gs.jd b/docs/html/guide/google/gcm/gs.jd new file mode 100644 index 0000000000000..5e426c2303b8a --- /dev/null +++ b/docs/html/guide/google/gcm/gs.jd @@ -0,0 +1,203 @@ +page.title=GCM: Getting Started +@jd:body + +This document describes how to write an Android application and the server-side logic, using the helper libraries (client and server) provided by GCM.
+ + +To create a Google API project:
+
Note: 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.
https://code.google.com/apis/console/#project:4815162342+ +
#project: (4815162342 in this example). This is your project ID, and it will be used later on as the GCM sender ID.To enable the GCM service:
+To obtain an API key:
+
+
+
+ Take note of the API key value (YourKeyWillBeShownHere) in this example, as it will be used later on.
Note: If you need to rotate the key, click Generate new key. A new key will be created while the old one will still be active for up to 24 hours. If you want to get rid of the old key immediately (for example, if you feel it was compromised), click Delete key.
+ +To perform the steps described in the following sections, you must first install the helper libraries (reference: client and server). 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: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.
This section describes the steps involved in writing an Android application that uses GCM.
+ To write your Android application, first copy the gcm.jar file from the SDK's gcm-client/dist directory to your application classpath.
<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="xx"/>+ +
<permission android:name="my_app_package.permission.C2D_MESSAGE" android:protectionLevel="signature" /> +<uses-permission android:name="my_app_package.permission.C2D_MESSAGE" />+
This permission must be called my_app_package.permission.C2D_MESSAGE (where my_app_package is the package name of your app as defined by the manifest tag), otherwise it will not work.
Note: This permission is not required if you are targeting your application to 4.1 or above (i.e., minSdkVersion 16)
+ +<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />+ +
<receiver android:name="com.google.android.gcm.GCMBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND" > + <intent-filter> + <action android:name="com.google.android.c2dm.intent.RECEIVE" /> + <action android:name="com.google.android.c2dm.intent.REGISTRATION" /> + <category android:name="my_app_package" /> + </intent-filter> +</receiver>+
This broadcast receiver is responsible for handling the 2 intents that can be sent by GCM (com.google.android.c2dm.intent.RECEIVE and com.google.android.c2dm.intent.REGISTRATION) and should be defined in the manifest (rather than programmatically) so that these intents can be received even if the application is not running. By setting the com.google.android.c2dm.permission.SEND permission, you are ensuring that only intents sent by the GCM system framework are sent to the receiver (a regular application cannot issue intents with that permission).
Notice that android:name in the category tag must be replaced by your application's package name (and the category tag is not required for applications targeted to minSdkVersion 16 and higher).
+
<service android:name=".GCMIntentService" />+ +
This intent service will be called by the GCMBroadcastReceiver (which is is provided by GCM library), as shown in the next step. It must be named my_app_package.GCMIntentService, unless you use a subclass of GCMBroadcastReceiver that overrides the method used to name the service.
Next write the my_app_package.GCMIntentService class, 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 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.
+ Note: The methods above run in the intent service's thread and hence are free to make network calls without the risk of blocking the UI thread.
+ +import com.google.android.gcm.GCMRegistrar;+
In the onCreate() method, add the following code:
GCMRegistrar.checkDevice(this);
+GCMRegistrar.checkManifest(this);
+final String regId = GCMRegistrar.getRegistrationId(this);
+if (regId.equals("")) {
+ GCMRegistrar.register(this, SENDER_ID);
+} else {
+ Log.v(TAG, "Already registered");
+}
+The checkDevice() method verifies that the device supports GCM and throws an exception if it does not (for instance, if it is an emulator that does not contain the Google APIs). Similarly, the checkManifest() method verifies that the application manifest contains meets all the requirements described in Writing the Android Application (this method is only necessary when you are developing the application; once the application is ready to be published, you can remove it).
Once the sanity checks are done, the device calls GCMRegsistrar.register() to register the device, passing the SENDER_ID you got when you signed up for GCM. But since the GCMRegistrar singleton keeps track of the registration ID upon the arrival of registration intents, you can call GCMRegistrar.getRegistrationId() first to check if the device is already registered.
Note: It is possible that the device was successfully registered to GCM but failed to send the registration ID to your server, in which case you should retry. See Advanced Topics for more details on how to handle this scenario.
+ +To write the server-side application:
+gcm-server.jar file from the SDK's gcm-server/dist directory to your server classpath.com.google.android.gcm.server.Sender helper class from the GCM library. For example:import com.google.android.gcm.server.*; + +Sender sender = new Sender(myApiKey); +Message message = new Message.Builder(regId).build(); +Result result = sender.send(message, 5);+ +
The snippet above does the following: +
Sender object using your project's API key.It's now necessary to parse the result and take the proper action in the following cases:
+NotRegistered, it's necessary to remove that registration ID, because the application was uninstalled from the device.Here's a code snippet that handles these 2 conditions:
+
+if (result.getMessageId() != null) {
+ String canonicalRegId = result.getCanonicalRegistrationId();
+ if (canonicalRegId != null) {
+ // same device has more than on registration ID: update database
+ }
+} else {
+ String error = result.getErrorCodeName();
+ if (error.equals(Constants.ERROR_NOT_REGISTERED)) {
+ // application has been removed from device - unregister database
+ }
+}
diff --git a/docs/html/guide/google/gcm/index.jd b/docs/html/guide/google/gcm/index.jd
new file mode 100644
index 0000000000000..cba8d0b19d0f3
--- /dev/null
+++ b/docs/html/guide/google/gcm/index.jd
@@ -0,0 +1,25 @@
+page.title=Google Cloud Messaging for Android
+@jd:body
+
+
+
Google Cloud Messaging for Android (GCM) is a service that helps developers send data from servers to their Android applications on Android devices. This could be a lightweight message telling the Android application that there is new data to be fetched from the server (for instance, a movie uploaded by a friend), or it could be a message containing up to 4kb of payload data (so apps like instant messaging can consume the message directly). The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device.
+ +To learn more about GCM, read the following documents:
+ +GCM also provides helper libraries for client and server development.
+ + diff --git a/docs/html/guide/google/gcm/server-javadoc/allclasses-frame.html b/docs/html/guide/google/gcm/server-javadoc/allclasses-frame.html new file mode 100644 index 0000000000000..d2fe43d85855e --- /dev/null +++ b/docs/html/guide/google/gcm/server-javadoc/allclasses-frame.html @@ -0,0 +1,43 @@ + + + + + +| Constants
+ +InvalidRequestException + +Message + +Message.Builder + +MulticastResult + +Result + +Sender + + |
+
| Constants
+ +InvalidRequestException + +Message + +Message.Builder + +MulticastResult + +Result + +Sender + + |
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++com.google.android.gcm.server.Constants +
public final class Constants
+Constants used on GCM service communication. +
+ +
+
| +Field Summary | +|
|---|---|
+static java.lang.String |
+ERROR_DEVICE_QUOTA_EXCEEDED
+
++ Too many messages sent by the sender to a specific device. |
+
+static java.lang.String |
+ERROR_INVALID_REGISTRATION
+
++ Bad registration_id. |
+
+static java.lang.String |
+ERROR_MESSAGE_TOO_BIG
+
++ The payload of the message is too big, see the limitations. |
+
+static java.lang.String |
+ERROR_MISMATCH_SENDER_ID
+
++ The sender_id contained in the registration_id does not match the + sender_id used to register with the GCM servers. |
+
+static java.lang.String |
+ERROR_MISSING_COLLAPSE_KEY
+
++ Collapse key is required. |
+
+static java.lang.String |
+ERROR_MISSING_REGISTRATION
+
++ Missing registration_id. |
+
+static java.lang.String |
+ERROR_NOT_REGISTERED
+
++ The user has uninstalled the application or turned off notifications. |
+
+static java.lang.String |
+ERROR_QUOTA_EXCEEDED
+
++ Too many messages sent by the sender. |
+
+static java.lang.String |
+ERROR_UNAVAILABLE
+
++ Used to indicate that a particular message could not be sent because + the GCM servers were not available. |
+
+static java.lang.String |
+GCM_SEND_ENDPOINT
+
++ Endpoint for sending messages. |
+
+static java.lang.String |
+JSON_CANONICAL_IDS
+
++ JSON-only field representing the number of messages with a canonical + registration id. |
+
+static java.lang.String |
+JSON_ERROR
+
++ JSON-only field representing the error field of an individual request. |
+
+static java.lang.String |
+JSON_FAILURE
+
++ JSON-only field representing the number of failed messages. |
+
+static java.lang.String |
+JSON_MESSAGE_ID
+
++ JSON-only field sent by GCM when a message was successfully sent. |
+
+static java.lang.String |
+JSON_MULTICAST_ID
+
++ JSON-only field representing the id of the multicast request. |
+
+static java.lang.String |
+JSON_PAYLOAD
+
++ JSON-only field representing the payload data. |
+
+static java.lang.String |
+JSON_REGISTRATION_IDS
+
++ JSON-only field representing the registration ids. |
+
+static java.lang.String |
+JSON_RESULTS
+
++ JSON-only field representing the result of each individual request. |
+
+static java.lang.String |
+JSON_SUCCESS
+
++ JSON-only field representing the number of successful messages. |
+
+static java.lang.String |
+PARAM_COLLAPSE_KEY
+
++ HTTP parameter for collapse key. |
+
+static java.lang.String |
+PARAM_DELAY_WHILE_IDLE
+
++ HTTP parameter for delaying the message delivery if the device is idle. |
+
+static java.lang.String |
+PARAM_PAYLOAD_PREFIX
+
++ Prefix to HTTP parameter used to pass key-values in the message payload. |
+
+static java.lang.String |
+PARAM_REGISTRATION_ID
+
++ HTTP parameter for registration id. |
+
+static java.lang.String |
+PARAM_TIME_TO_LIVE
+
++ Prefix to HTTP parameter used to set the message time-to-live. |
+
+static java.lang.String |
+TOKEN_CANONICAL_REG_ID
+
++ Token returned by GCM when the requested registration id has a canonical + value. |
+
+static java.lang.String |
+TOKEN_ERROR
+
++ Token returned by GCM when there was an error sending a message. |
+
+static java.lang.String |
+TOKEN_MESSAGE_ID
+
++ Token returned by GCM when a message was successfully sent. |
+
| +Method Summary | +
|---|
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Field Detail | +
|---|
+public static final java.lang.String GCM_SEND_ENDPOINT+
+
+public static final java.lang.String PARAM_REGISTRATION_ID+
+
+public static final java.lang.String PARAM_COLLAPSE_KEY+
+
+public static final java.lang.String PARAM_DELAY_WHILE_IDLE+
+
+public static final java.lang.String PARAM_PAYLOAD_PREFIX+
+
+public static final java.lang.String PARAM_TIME_TO_LIVE+
+
+public static final java.lang.String ERROR_QUOTA_EXCEEDED+
+
+public static final java.lang.String ERROR_DEVICE_QUOTA_EXCEEDED+
+
+public static final java.lang.String ERROR_MISSING_REGISTRATION+
+
+public static final java.lang.String ERROR_INVALID_REGISTRATION+
+
+public static final java.lang.String ERROR_MISMATCH_SENDER_ID+
+
+public static final java.lang.String ERROR_NOT_REGISTERED+
+
+public static final java.lang.String ERROR_MESSAGE_TOO_BIG+
+
+public static final java.lang.String ERROR_MISSING_COLLAPSE_KEY+
+
+public static final java.lang.String ERROR_UNAVAILABLE+
+
+public static final java.lang.String TOKEN_MESSAGE_ID+
+
+public static final java.lang.String TOKEN_CANONICAL_REG_ID+
+
+public static final java.lang.String TOKEN_ERROR+
+
+public static final java.lang.String JSON_REGISTRATION_IDS+
+
+public static final java.lang.String JSON_PAYLOAD+
+
+public static final java.lang.String JSON_SUCCESS+
+
+public static final java.lang.String JSON_FAILURE+
+
+public static final java.lang.String JSON_CANONICAL_IDS+
+
+public static final java.lang.String JSON_MULTICAST_ID+
+
+public static final java.lang.String JSON_RESULTS+
+
+public static final java.lang.String JSON_ERROR+
+
+public static final java.lang.String JSON_MESSAGE_ID+
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class InvalidRequestException
+Exception thrown when GCM returned an error due to an invalid request. +
+ This is equivalent to GCM posts that return an HTTP error different of 200. +
+ +
+
| +Constructor Summary | +|
|---|---|
InvalidRequestException(int status)
+
++ |
+|
InvalidRequestException(int status,
+ java.lang.String description)
+
++ |
+|
| +Method Summary | +|
|---|---|
+ java.lang.String |
+getDescription()
+
++ Gets the error description. |
+
+ int |
+getHttpStatusCode()
+
++ Gets the HTTP Status Code. |
+
| Methods inherited from class java.lang.Throwable | +
|---|
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
+
| +Constructor Detail | +
|---|
+public InvalidRequestException(int status)+
+public InvalidRequestException(int status, + java.lang.String description)+
| +Method Detail | +
|---|
+public int getHttpStatusCode()+
+
+public java.lang.String getDescription()+
+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public static final class Message.Builder
+
| +Constructor Summary | +|
|---|---|
Message.Builder()
+
++ |
+|
| +Method Summary | +|
|---|---|
+ Message.Builder |
+addData(java.lang.String key,
+ java.lang.String value)
+
++ Adds a key/value pair to the payload data. |
+
+ Message |
+build()
+
++ |
+
+ Message.Builder |
+collapseKey(java.lang.String value)
+
++ Sets the collapseKey property. |
+
+ Message.Builder |
+delayWhileIdle(boolean value)
+
++ Sets the delayWhileIdle property (default value is false). |
+
+ Message.Builder |
+timeToLive(int value)
+
++ Sets the time to live, in seconds. |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Constructor Detail | +
|---|
+public Message.Builder()+
| +Method Detail | +
|---|
+public Message.Builder collapseKey(java.lang.String value)+
+
+public Message.Builder delayWhileIdle(boolean value)+
+
+public Message.Builder timeToLive(int value)+
+
+public Message.Builder addData(java.lang.String key, + java.lang.String value)+
+
+public Message build()+
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class Message
+GCM message. + +
+ Instances of this class are immutable and should be created using a
+ Message.Builder. Examples:
+
+ Simplest message:
+
+ Message message = new Message.Builder().build();
+
+ Message message = new Message.Builder()
+ .collapseKey(collapseKey)
+ .timeToLive(3)
+ .delayWhileIdle(true)
+ .build();
+
+ Message message = new Message.Builder()
+ .collapseKey(collapseKey)
+ .timeToLive(3)
+ .delayWhileIdle(true)
+ .addData("key1", "value1")
+ .addData("key2", "value2")
+ .build();
+ + +
+
| +Nested Class Summary | +|
|---|---|
+static class |
+Message.Builder
+
++ |
+
| +Method Summary | +|
|---|---|
+ java.lang.String |
+getCollapseKey()
+
++ Gets the collapse key. |
+
+ java.util.Map<java.lang.String,java.lang.String> |
+getData()
+
++ Gets the payload data, which is immutable. |
+
+ java.lang.Integer |
+getTimeToLive()
+
++ Gets the time to live (in seconds). |
+
+ java.lang.Boolean |
+isDelayWhileIdle()
+
++ Gets the delayWhileIdle flag. |
+
+ java.lang.String |
+toString()
+
++ |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
+
| +Method Detail | +
|---|
+public java.lang.String getCollapseKey()+
+
+public java.lang.Boolean isDelayWhileIdle()+
+
+public java.lang.Integer getTimeToLive()+
+
+public java.util.Map<java.lang.String,java.lang.String> getData()+
+
+public java.lang.String toString()+
toString in class java.lang.Object
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class MulticastResult
+Result of a GCM multicast message request . +
+ +
+
| +Method Summary | +|
|---|---|
+ int |
+getCanonicalIds()
+
++ Gets the number of successful messages that also returned a canonical + registration id. |
+
+ int |
+getFailure()
+
++ Gets the number of failed messages. |
+
+ long |
+getMulticastId()
+
++ Gets the multicast id. |
+
+ java.util.List<Result> |
+getResults()
+
++ Gets the results of each individual message, which is immutable. |
+
+ java.util.List<java.lang.Long> |
+getRetryMulticastIds()
+
++ Gets additional ids if more than one multicast message was sent. |
+
+ int |
+getSuccess()
+
++ Gets the number of successful messages. |
+
+ int |
+getTotal()
+
++ Gets the total number of messages sent, regardless of the status. |
+
+ java.lang.String |
+toString()
+
++ |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
+
| +Method Detail | +
|---|
+public long getMulticastId()+
+
+public int getSuccess()+
+
+public int getTotal()+
+
+public int getFailure()+
+
+public int getCanonicalIds()+
+
+public java.util.List<Result> getResults()+
+
+public java.util.List<java.lang.Long> getRetryMulticastIds()+
+
+public java.lang.String toString()+
toString in class java.lang.Object
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public final class Result
+Result of a GCM message request that returned HTTP status code 200. + +
+ If the message is successfully created, the getMessageId() returns
+ the message id and getErrorCodeName() returns null;
+ otherwise, getMessageId() returns null and
+ getErrorCodeName() returns the code of the error.
+
+
+ There are cases when a request is accept and the message successfully + created, but GCM has a canonical registration id for that device. In this + case, the server should update the registration id to avoid rejected requests + in the future. + +
+ In a nutshell, the workflow to handle a result is: +
+ - Call+getMessageId(): + - null means error, callgetErrorCodeName()+ - non-null means the message was created: + - CallgetCanonicalRegistrationId()+ - if it returns null, do nothing. + - otherwise, update the server datastore with the new id. +
+ +
+
| +Method Summary | +|
|---|---|
+ java.lang.String |
+getCanonicalRegistrationId()
+
++ Gets the canonical registration id, if any. |
+
+ java.lang.String |
+getErrorCodeName()
+
++ Gets the error code, if any. |
+
+ java.lang.String |
+getMessageId()
+
++ Gets the message id, if any. |
+
+ java.lang.String |
+toString()
+
++ |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
+
| +Method Detail | +
|---|
+public java.lang.String getMessageId()+
+
+public java.lang.String getCanonicalRegistrationId()+
+
+public java.lang.String getErrorCodeName()+
+
+public java.lang.String toString()+
toString in class java.lang.Object
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
+java.lang.Object ++
public class Sender
+Helper class to send messages to the GCM service using an API Key. +
+ +
+
| +Field Summary | +|
|---|---|
+protected static int |
+BACKOFF_INITIAL_DELAY
+
++ Initial delay before first retry, without jitter. |
+
+protected java.util.logging.Logger |
+logger
+
++ |
+
+protected static int |
+MAX_BACKOFF_DELAY
+
++ Maximum delay before a retry. |
+
+protected java.util.Random |
+random
+
++ |
+
+protected static java.lang.String |
+UTF8
+
++ |
+
| +Constructor Summary | +|
|---|---|
Sender(java.lang.String key)
+
++ Default constructor. |
+|
| +Method Summary | +|
|---|---|
+protected static void |
+addParameter(java.lang.StringBuilder body,
+ java.lang.String name,
+ java.lang.String value)
+
++ Adds a new parameter to the HTTP POST body. |
+
+protected java.net.HttpURLConnection |
+getConnection(java.lang.String url)
+
++ Gets an HttpURLConnection given an URL. |
+
+protected static java.lang.String |
+getString(java.io.InputStream stream)
+
++ Convenience method to convert an InputStream to a String. |
+
+protected static java.lang.StringBuilder |
+newBody(java.lang.String name,
+ java.lang.String value)
+
++ Creates a StringBuilder to be used as the body of an HTTP POST. |
+
+protected static java.util.Map<java.lang.String,java.lang.String> |
+newKeyValues(java.lang.String key,
+ java.lang.String value)
+
++ Creates a map with just one key-value pair. |
+
+protected java.net.HttpURLConnection |
+post(java.lang.String url,
+ java.lang.String body)
+
++ Make an HTTP post to a given URL. |
+
+protected java.net.HttpURLConnection |
+post(java.lang.String url,
+ java.lang.String contentType,
+ java.lang.String body)
+
++ |
+
+ MulticastResult |
+send(Message message,
+ java.util.List<java.lang.String> regIds,
+ int retries)
+
++ Sends a message to many devices, retrying in case of unavailability. |
+
+ Result |
+send(Message message,
+ java.lang.String registrationId,
+ int retries)
+
++ Sends a message to one device, retrying in case of unavailability. |
+
+ MulticastResult |
+sendNoRetry(Message message,
+ java.util.List<java.lang.String> registrationIds)
+
++ Sends a message without retrying in case of service unavailability. |
+
+ Result |
+sendNoRetry(Message message,
+ java.lang.String registrationId)
+
++ Sends a message without retrying in case of service unavailability. |
+
| Methods inherited from class java.lang.Object | +
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
+
| +Field Detail | +
|---|
+protected static final java.lang.String UTF8+
+protected static final int BACKOFF_INITIAL_DELAY+
+
+protected static final int MAX_BACKOFF_DELAY+
+
+protected final java.util.Random random+
+protected final java.util.logging.Logger logger+
| +Constructor Detail | +
|---|
+public Sender(java.lang.String key)+
+
key - API key obtained through the Google API Console.| +Method Detail | +
|---|
+public Result send(Message message, + java.lang.String registrationId, + int retries) + throws java.io.IOException+
+ Note: this method uses exponential back-off to retry in + case of service unavailability and hence could block the calling thread + for many seconds. +
+
message - message to be sent, including the device's registration id.registrationId - device where the message will be sent.retries - number of retries in case of service unavailability errors.
+java.lang.IllegalArgumentException - if registrationId is null.
+InvalidRequestException - if GCM didn't returned a 200 or 503 status.
+java.io.IOException - if message could not be sent.+public Result sendNoRetry(Message message, + java.lang.String registrationId) + throws java.io.IOException+
send(Message, String, int) for more info.
++
InvalidRequestException - if GCM didn't returned a 200 or 503 status.
+java.lang.IllegalArgumentException - if registrationId is null.
+java.io.IOException+public MulticastResult send(Message message, + java.util.List<java.lang.String> regIds, + int retries) + throws java.io.IOException+
+ Note: this method uses exponential back-off to retry in + case of service unavailability and hence could block the calling thread + for many seconds. +
+
message - message to be sent.regIds - registration id of the devices that will receive
+ the message.retries - number of retries in case of service unavailability errors.
+java.lang.IllegalArgumentException - if registrationIds is null or
+ empty.
+InvalidRequestException - if GCM didn't returned a 200 or 503 status.
+java.io.IOException - if message could not be sent.+public MulticastResult sendNoRetry(Message message, + java.util.List<java.lang.String> registrationIds) + throws java.io.IOException+
send(Message, List, int) for more info.
++
java.lang.IllegalArgumentException - if registrationIds is null or
+ empty.
+InvalidRequestException - if GCM didn't returned a 200 status.
+java.io.IOException - if message could not be sent or received.+protected java.net.HttpURLConnection post(java.lang.String url, + java.lang.String body) + throws java.io.IOException+
+
java.io.IOException+protected java.net.HttpURLConnection post(java.lang.String url, + java.lang.String contentType, + java.lang.String body) + throws java.io.IOException+
java.io.IOException+protected static final java.util.Map<java.lang.String,java.lang.String> newKeyValues(java.lang.String key, + java.lang.String value)+
+
+protected static java.lang.StringBuilder newBody(java.lang.String name, + java.lang.String value)+
StringBuilder to be used as the body of an HTTP POST.
++
name - initial parameter for the POST.value - initial value for that parameter.
++protected static void addParameter(java.lang.StringBuilder body, + java.lang.String name, + java.lang.String value)+
+
body - HTTP POST bodyname - parameter's namevalue - parameter's value+protected java.net.HttpURLConnection getConnection(java.lang.String url) + throws java.io.IOException+
HttpURLConnection given an URL.
++
java.io.IOException+protected static java.lang.String getString(java.io.InputStream stream) + throws java.io.IOException+
+ If the stream ends in a newline character, it will be stripped. +
+
java.io.IOException
+
+
|
++ + | +|||||||
| + PREV CLASS + NEXT CLASS | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| + SUMMARY: NESTED | FIELD | CONSTR | METHOD | ++DETAIL: FIELD | CONSTR | METHOD | +|||||||
|
+Classes
+
+ +Constants + +Message + +Message.Builder + +MulticastResult + +Result + +Sender |
+
|
+Exceptions
+
+ +InvalidRequestException |
+
+
+
|
++ + | +|||||||
| + PREV PACKAGE + NEXT PACKAGE | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| +Class Summary | +|
|---|---|
| Constants | +Constants used on GCM service communication. | +
| Message | +GCM message. | +
| Message.Builder | ++ |
| MulticastResult | +Result of a GCM multicast message request . | +
| Result | +Result of a GCM message request that returned HTTP status code 200. | +
| Sender | +Helper class to send messages to the GCM service using an API Key. | +
+ +
| +Exception Summary | +|
|---|---|
| InvalidRequestException | +Exception thrown when GCM returned an error due to an invalid request. | +
+
+
+
|
++ + | +|||||||
| + PREV PACKAGE + NEXT PACKAGE | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| +com.google.* | +
|---|
+ +
| com.google.android.gcm.server.Constants | +||
|---|---|---|
+public static final java.lang.String |
+ERROR_DEVICE_QUOTA_EXCEEDED |
+"DeviceQuotaExceeded" |
+
+public static final java.lang.String |
+ERROR_INVALID_REGISTRATION |
+"InvalidRegistration" |
+
+public static final java.lang.String |
+ERROR_MESSAGE_TOO_BIG |
+"MessageTooBig" |
+
+public static final java.lang.String |
+ERROR_MISMATCH_SENDER_ID |
+"MismatchSenderId" |
+
+public static final java.lang.String |
+ERROR_MISSING_COLLAPSE_KEY |
+"MissingCollapseKey" |
+
+public static final java.lang.String |
+ERROR_MISSING_REGISTRATION |
+"MissingRegistration" |
+
+public static final java.lang.String |
+ERROR_NOT_REGISTERED |
+"NotRegistered" |
+
+public static final java.lang.String |
+ERROR_QUOTA_EXCEEDED |
+"QuotaExceeded" |
+
+public static final java.lang.String |
+ERROR_UNAVAILABLE |
+"Unavailable" |
+
+public static final java.lang.String |
+GCM_SEND_ENDPOINT |
+"https://android.googleapis.com/gcm/send" |
+
+public static final java.lang.String |
+JSON_CANONICAL_IDS |
+"canonical_ids" |
+
+public static final java.lang.String |
+JSON_ERROR |
+"error" |
+
+public static final java.lang.String |
+JSON_FAILURE |
+"failure" |
+
+public static final java.lang.String |
+JSON_MESSAGE_ID |
+"message_id" |
+
+public static final java.lang.String |
+JSON_MULTICAST_ID |
+"multicast_id" |
+
+public static final java.lang.String |
+JSON_PAYLOAD |
+"data" |
+
+public static final java.lang.String |
+JSON_REGISTRATION_IDS |
+"registration_ids" |
+
+public static final java.lang.String |
+JSON_RESULTS |
+"results" |
+
+public static final java.lang.String |
+JSON_SUCCESS |
+"success" |
+
+public static final java.lang.String |
+PARAM_COLLAPSE_KEY |
+"collapse_key" |
+
+public static final java.lang.String |
+PARAM_DELAY_WHILE_IDLE |
+"delay_while_idle" |
+
+public static final java.lang.String |
+PARAM_PAYLOAD_PREFIX |
+"data." |
+
+public static final java.lang.String |
+PARAM_REGISTRATION_ID |
+"registration_id" |
+
+public static final java.lang.String |
+PARAM_TIME_TO_LIVE |
+"time_to_live" |
+
+public static final java.lang.String |
+TOKEN_CANONICAL_REG_ID |
+"registration_id" |
+
+public static final java.lang.String |
+TOKEN_ERROR |
+"Error" |
+
+public static final java.lang.String |
+TOKEN_MESSAGE_ID |
+"id" |
+
+ +
+ +
| com.google.android.gcm.server.Sender | +||
|---|---|---|
+protected static final int |
+BACKOFF_INITIAL_DELAY |
+1000 |
+
+protected static final int |
+MAX_BACKOFF_DELAY |
+1024000 |
+
+protected static final java.lang.String |
+UTF8 |
+"UTF-8" |
+
+ +
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+ +++Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
+- Interfaces (italic)
- Classes
- Enums
- Exceptions
- Errors
- Annotation Types
+ ++ ++Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.- Class inheritance diagram
- Direct Subclasses
- All Known Subinterfaces
- All Known Implementing Classes
- Class/interface declaration
- Class/interface description +
+
- Nested Class Summary
- Field Summary
- Constructor Summary
- Method Summary +
+
- Field Detail
- Constructor Detail
- Method Detail
+ ++ ++Each annotation type has its own separate page with the following sections:
+
+- Annotation Type declaration
- Annotation Type description
- Required Element Summary
- Optional Element Summary
- Element Detail
+ +++Each enum has its own separate page with the following sections:
+
+- Enum declaration
- Enum description
- Enum Constant Summary
- Enum Constant Detail
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with+java.lang.Object. The interfaces do not inherit fromjava.lang.Object.+
+- When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
- When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.+
+
+
+
+
+This help file applies to API documentation generated using the standard doclet.
+
+
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
HttpURLConnection given an URL.
+StringBuilder to be used as the body of an HTTP POST.
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||
| +Package com.google.android.gcm.server | +
|---|
| +Class com.google.android.gcm.server.InvalidRequestException extends java.io.IOException implements Serializable | +
|---|
| +Serialized Fields | +
|---|
+int status+
+java.lang.String description+
| +Class com.google.android.gcm.server.Message extends java.lang.Object implements Serializable | +
|---|
| +Serialized Fields | +
|---|
+java.lang.String collapseKey+
+java.lang.Boolean delayWhileIdle+
+java.lang.Integer timeToLive+
+java.util.Map<K,V> data+
| +Class com.google.android.gcm.server.MulticastResult extends java.lang.Object implements Serializable | +
|---|
| +Serialized Fields | +
|---|
+int success+
+int failure+
+int canonicalIds+
+long multicastId+
+java.util.List<E> results+
+java.util.List<E> retryMulticastIds+
| +Class com.google.android.gcm.server.Result extends java.lang.Object implements Serializable | +
|---|
| +Serialized Fields | +
|---|
+java.lang.String messageId+
+java.lang.String canonicalRegistrationId+
+java.lang.String errorCode+
+
+
+
|
++ + | +|||||||
| + PREV + NEXT | ++ FRAMES + NO FRAMES + + + + + | +|||||||