From 0137175af92b631932c03660baf4f634b65001b8 Mon Sep 17 00:00:00 2001 From: kmccormick Date: Fri, 12 Dec 2014 15:00:37 -0800 Subject: Doc change: refactor GCM docs to be platform-agnostic. Fix for: b/17733410 Change-Id: I6dabe6d0985dac7cf280c780140339c6250ac6e2 --- docs/html/google/gcm/adv.jd | 410 ------------------ docs/html/google/gcm/c2dm.jd | 12 +- docs/html/google/gcm/ccs.jd | 58 +-- docs/html/google/gcm/client.jd | 146 ++++--- docs/html/google/gcm/gcm.jd | 339 ++++++++------- docs/html/google/gcm/gs.jd | 17 +- docs/html/google/gcm/http.jd | 129 +++--- docs/html/google/gcm/notifications.jd | 6 - docs/html/google/gcm/server-ref.jd | 763 ++++++++++++++++++++++++++++++++++ docs/html/google/gcm/server.jd | 648 +++++++++++++++-------------- docs/html/google/google_toc.cs | 13 +- 11 files changed, 1445 insertions(+), 1096 deletions(-) delete mode 100644 docs/html/google/gcm/adv.jd create mode 100644 docs/html/google/gcm/server-ref.jd (limited to 'docs/html/google') diff --git a/docs/html/google/gcm/adv.jd b/docs/html/google/gcm/adv.jd deleted file mode 100644 index 95497e3..0000000 --- a/docs/html/google/gcm/adv.jd +++ /dev/null @@ -1,410 +0,0 @@ -page.title=GCM Advanced Topics -@jd:body - -
- -
-

This document covers advanced topics for GCM.

- - - - -

Lifetime of a Message

-

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. -Collapsible messages are also called send-to-sync messages.

- -

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

-Likewise, there is a limit on how many collapse_keys you can have for -a particular device. GCM allows a maximum of 4 different collapse keys to be used -by the GCM server per device -any given time. In other words, the GCM server can simultaneously store 4 different -send-to-sync messages, each with a different collapse key. If you exceed this number -GCM will only keep 4 collapse keys, with no guarantees about which ones they will be. -See Send-to-sync messages for more information. -

- -

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.

- -

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 Cloud Console stats are broken down by messages sent to device, messages -collapsed, and messages waiting for delivery.

- -

Throttling

-

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.

- -

Keeping the Registration State in Sync

-

Whenever the application registers as described in -Implementing GCM Client, -it should save the registration 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).

-

Canonical IDs

-

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.

- -

Automatic Retry Using Exponential Back-Off

- -

When registration or unregistration fails, the app should retry the failed operation.

-

In the simplest case, if your application attempts to 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 {@link android.app.PendingIntent} to retry the operation. - -

Unregistration

- -

This section explains when you should unregister in GCM and what happens -when you do.

- -

Why you should rarely unregister

- -

A registration ID (regID) represents a particular Android application running -on a particular device. You should only need to unregister in rare cases, such as -if you want an app to stop receiving messages, or if you suspect that the regID has -been compromised. In general, though, once an app has a regID, you shouldn't need -to change it.

- -

In particular, you should never unregister your app as a mechanism for -logout or for switching between users, for the following reasons:

- - - - -

The solution is to manage your own mapping between users, the regID, and -individual messages:

- - - - -

How unregistration works

- -

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:

-
    -
  1. The end user uninstalls the application.
    2. -
  2. The 3rd-party server sends a message to GCM server.
    3. -
  3. The GCM server sends the message to the device.
    4. -
  4. The GCM client receives the message and queries Package Manager about -whether there are broadcast receivers configured to receive it, which returns -false. -
    5. -
  5. The GCM client informs the GCM server that the application was uninstalled.
    6. -
  6. The GCM server marks the registration ID for deletion.
    7. -
  7. The 3rd-party server sends a message to GCM.
    8. -
  8. The GCM returns a NotRegistered error message to the 3rd-party server.
    9. -
  9. The 3rd-party deletes the registration ID. -
    10. -
- -

Note: The GCM client is the Google Cloud -Messaging framework present on the device.

- -

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).

- -

Send-to-Sync vs. Messages with Payload

- -

Every message sent in GCM has the following characteristics:

- - -

But despite these similarities, messages can behave very differently depending -on their particular settings. One major distinction between messages is whether -they are collapsed (where each new message replaces the preceding message) or not -collapsed (where each individual message is delivered). Every message sent in GCM -is either a "send-to-sync" (collapsible) message or a "message with -payload" (non-collapsible message). These concepts are described in more -detail in the following sections.

- -

Send-to-sync messages

- -

A send-to-sync (collapsible) message is often 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. Another -example would be a sports application that updates users with the latest score. -Only the most recent message is relevant, so it makes sense to have each new -message replace the preceding message.

- -

The email and sports applications are cases where you would probably 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 most recent 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 per device, each with a different collapse key. -For example, Device A can have A1, A2, A3, and A4. Device B can have B1, B2, B3, -and B4, and so on. If you exceed this number GCM will only keep 4 collapse keys, with no -guarantees about which ones they will be.

- -

Messages with payload

- -

Unlike a send-to-sync message, every "message with payload" -(non-collapsible message) is delivered. The payload the message contains can be -up to 4kb. 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 -extra message_type, for which the value is always the string -"deleted_messages".

- -

The application should respond by syncing with the server to recover the -discarded messages.

- -

Which should I use?

-

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. However, if you use collapsible messages, remember that -GCM only allows a maximum of 4 different collapse keys to be used by the GCM server -per device at any given time. You must not exceed this number, or it could cause -unpredictable consequences.

- -

Setting an Expiration Date for a Message

-

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:

- -

Background

-

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
-},
-
- - -

Receiving Messages from Multiple Senders

- -

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 number. 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/google/gcm/c2dm.jd b/docs/html/google/gcm/c2dm.jd index 5c4a86e..fc95c2b 100644 --- a/docs/html/google/gcm/c2dm.jd +++ b/docs/html/google/gcm/c2dm.jd @@ -79,7 +79,7 @@ page.title=Migration

Relationship between C2DM and GCM

-

C2DM and GCM are not interoperable. For example, you cannot post notifications from GCM to C2DM registration IDs, nor can you use C2DM registration IDs as GCM registration IDs. From your server-side application, you must keep keep track of whether a registration ID is from C2DM or GCM and use the proper endpoint.

+

C2DM and GCM are not interoperable. For example, you cannot post notifications from GCM to C2DM registration IDs, nor can you use C2DM registration IDs as GCM registration IDs. From your server-side application, you must keep track of whether a registration ID is from C2DM or GCM and use the proper endpoint.

As you transition from C2DM to GCM, your server needs to be aware of whether a given registration ID contains an old C2DM sender or a new GCM project number. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.

@@ -87,13 +87,11 @@ contains an old C2DM sender or a new GCM project number. This is the approach we

Migrating Your Apps

This section describes how to move existing C2DM apps to GCM.

Client changes

-

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 number 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);
+

Migration is simple! Just re-register the client app for your target GCM-enabled platform. For + example, see Register for GCM

+

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.

+

Server changes

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:

diff --git a/docs/html/google/gcm/ccs.jd b/docs/html/google/gcm/ccs.jd index 6332b8d..143b057 100644 --- a/docs/html/google/gcm/ccs.jd +++ b/docs/html/google/gcm/ccs.jd @@ -36,6 +36,7 @@ page.title=GCM Cloud Connection Server (XMPP)

See Also

    +
  1. Server Reference
  2. HTTP
  3. Getting Started
  4. Implementing GCM Server
    5. @@ -73,8 +74,8 @@ Play services platform. Upstream messaging is available through the APIs. For examples, see Implementing an XMPP-based App Server.

    -

    Note: See -Implementing GCM Server for a list of all the message +

    Note: See the +Server Reference for a list of all the message parameters and which connection server(s) supports them.

    Establishing a Connection

    @@ -176,8 +177,8 @@ operation and your server needs to resend the messages. See Flow Control for details.

    -

    Note: See -Implementing GCM Server for a list of all the message +

    Note: See the +Server Reference for a list of all the message parameters and which connection server(s) supports them.

    Request format

    @@ -278,56 +279,11 @@ message is "nack". A NACK message contains:

    </message> -

    The following table lists NACK error codes. Unless otherwise +

    See the Server Reference for a complete list of the +NACK error codes. Unless otherwise indicated, a NACKed message should not be retried. Unexpected NACK error codes should be treated the same as {@code INTERNAL_SERVER_ERROR}.

    -

    - Table 1. NACK error codes.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Error CodeDescription
    {@code BAD_ACK}The ACK message is improperly formed.
    {@code BAD_REGISTRATION}The device has a registration ID, but it's invalid or expired.
    {@code CONNECTION_DRAINING}The message couldn't be processed because the connection is draining. The -message should be immediately retried over another connection.
    {@code DEVICE_UNREGISTERED}The device is not registered.
    {@code INTERNAL_SERVER_ERROR}The server encountered an error while trying to process the request.
    {@code INVALID_JSON}The JSON message payload is not valid.
    {@code DEVICE_MESSAGE_RATE_EXCEEDED}The rate of messages to a particular device is too high. You should reduce -the number of messages sent to this device and should not immediately retry -sending to this device. This error code is replacing {@code QUOTA_EXCEEDED}.
    {@code SERVICE_UNAVAILABLE}CCS is not currently able to process the message. The - message should be retried over the same connection using exponential backoff - with an initial delay of 1 second.
    -

    Stanza error

    You can also get a stanza error in certain cases. diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd index d44ee3c..9cb3f84 100644 --- a/docs/html/google/gcm/client.jd +++ b/docs/html/google/gcm/client.jd @@ -1,4 +1,4 @@ -page.title=Implementing GCM Client +page.title=Implementing GCM Client on Android page.tags=cloud,push,messaging @jd:body @@ -15,8 +15,8 @@ page.tags=cloud,push,messaging

    1. Check for Google Play Services APK
    2. Register for GCM
      3. -
    3. Send a message
      4. -
    4. Receive a message
      5. +
    5. Receive a downstream message
      6. +
    6. Send an upstream message
  5. Running the Sample
  6. Viewing Statistics
    7. @@ -34,14 +34,26 @@ page.tags=cloud,push,messaging -

    A Google Cloud Messaging (GCM) client is a GCM-enabled app that runs on an +

    A Google Cloud Messaging (GCM) Android client is a GCM-enabled app that runs on an Android device. To write your client code, we recommend that you use the -GCM APIs. -The client helper library that was offered in previous versions of GCM still works, -but it has been superseded by the more efficient - -GCM APIs.

    +{@code GoogleCloudMessaging} API.

    + +

    Here are the requirements for running a GCM Android client:

    + +

    A full GCM implementation requires both a client implementation and a server implementation. For more @@ -58,7 +70,7 @@ registration ID), and a broadcast receiver to receive messages sent by GCM.

    To write your client application, use the -GCM APIs. +{@code GoogleCloudMessaging} API. To use this API, you must set up your project to use the Google Play services SDK, as described in Setup Google Play Services SDK.

    @@ -88,9 +100,6 @@ If you're using Android Studio, this is the string to add to the the Android application can register and receive messages.
  7. The android.permission.INTERNET permission so the Android application can send the registration ID to the 3rd party server.
    8. -
  8. The 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)
  9. The android.permission.WAKE_LOCK permission so the application can keep the processor from sleeping when a message is received. Optional—use only if the app wants to keep the device from sleeping.
    10. @@ -101,7 +110,7 @@ pattern—otherwise the Android application will not receive the messages.A receiver for com.google.android.c2dm.intent.RECEIVE, with the category set as applicationPackage. The receiver should require the -com.google.android.c2dm.SEND permission, so that only the GCM +com.google.android.c2dm.permission.SEND permission, so that only the GCM Framework can send a message to it. If your app uses an {@link android.app.IntentService} (not required, but a common pattern), this receiver should be an instance of {@link android.support.v4.content.WakefulBroadcastReceiver}. @@ -324,8 +333,8 @@ private String getRegistrationId(Context context) { return ""; } // Check if app was updated; if so, it must clear the registration ID - // since the existing regID is not guaranteed to work with the new - // app version. + // since the existing registration ID is not guaranteed to work with + // the new app version. int registeredVersion = prefs.getInt(PROPERTY_APP_VERSION, Integer.MIN_VALUE); int currentVersion = getAppVersion(context); if (registeredVersion != currentVersion) { @@ -340,14 +349,14 @@ private String getRegistrationId(Context context) { */ private SharedPreferences getGCMPreferences(Context context) { // This sample app persists the registration ID in shared preferences, but - // how you store the regID in your app is up to you. + // how you store the registration ID in your app is up to you. return getSharedPreferences(DemoActivity.class.getSimpleName(), Context.MODE_PRIVATE); }

    If the registration ID doesn't exist or the app was updated, {@code getRegistrationId()} returns an empty string -to indicate that the app needs to get a new regID. {@code getRegistrationId()} calls +to indicate that the app needs to get a new registration ID. {@code getRegistrationId()} calls the following method to check the app version:

    /**
@@ -400,7 +409,7 @@ private void registerInBackground() {
                 // will send upstream messages to a server that echo back the
                 // message using the 'from' address in the message.
 
-                // Persist the regID - no need to register again.
+                // Persist the registration ID - no need to register again.
                 storeRegistrationId(context, regid);
             } catch (IOException ex) {
                 msg = "Error :" + ex.getMessage();
@@ -433,7 +442,8 @@ private void sendRegistrationIdToBackend() {
 
 
    After registering, the app calls {@code storeRegistrationId()} to store the
 registration ID in shared preferences for future use. This is just one way of
-persisting a regID. You might choose to use a different approach in your app:
    
+persisting a registration ID. You might choose to use a different approach in
+your app:
    
 
 
    /**
  * Stores the registration ID and app versionCode in the application's
@@ -455,64 +465,22 @@ private void storeRegistrationId(Context context, String regId) {
 
    Handle registration errors
    
 
 
    As stated above, an Android app must register with GCM servers and get a registration ID
-(regID) before it can receive messages. A given regID is not guaranteed to last indefinitely,
-so the first thing your app should always do is check to make sure it has a valid regID
-(as shown in the code snippets above).
    
+before it can receive messages. A given registration ID is not guaranteed to last indefinitely,
+so the first thing your app should always do is check to make sure it has a valid
+registration ID (as shown in the code snippets above).
    
 
-
    In addition to confirming that it has a valid regID, your app should be prepared to handle
+
    In addition to confirming that it has a valid registration ID, your app should be prepared to handle
 the registration error {@code TOO_MANY_REGISTRATIONS}. This error indicates that the device
 has too many apps registered with GCM. The error only occurs in cases where there are
 extreme numbers of apps, so it should not affect the average user. The remedy is to prompt
-the user to delete some of the other GCM-enabled apps from the device to make
+the user to delete some of the other client apps from the device to make
 room for the new one.
    
 
-
-
    Send a message
    
-
    When the user clicks the app's Send button, the app sends an
-upstream message using the
-
-{@code GoogleCloudMessaging} API. In order to receive the upstream message,
-your server should be connected to CCS. You can use one of the demo servers in
-Implementing an XMPP-based App Server to run the sample and connect
-to CCS.
    
-
-
    public void onClick(final View view) {
-    if (view == findViewById(R.id.send)) {
-        new AsyncTask() {
-            @Override
-            protected String doInBackground(Void... params) {
-                String msg = "";
-                try {
-                    Bundle data = new Bundle();
-                        data.putString("my_message", "Hello World");
-                        data.putString("my_action",
-                                "com.google.android.gcm.demo.app.ECHO_NOW");
-                        String id = Integer.toString(msgId.incrementAndGet());
-                        gcm.send(SENDER_ID + "@gcm.googleapis.com", id, data);
-                        msg = "Sent message";
-                } catch (IOException ex) {
-                    msg = "Error :" + ex.getMessage();
-                }
-                return msg;
-            }
-
-            @Override
-            protected void onPostExecute(String msg) {
-                mDisplay.append(msg + "\n");
-            }
-        }.execute(null, null, null);
-    } else if (view == findViewById(R.id.clear)) {
-        mDisplay.setText("");
-    }
-}
    
-
-
    Receive a message
    
+
    Receive a downstream message
    
 
 
    As described above in Step 2, the app includes a
 {@link android.support.v4.content.WakefulBroadcastReceiver} for the com.google.android.c2dm.intent.RECEIVE
-intent. A broadcast receiver is the mechanism GCM uses to deliver messages. When {@code onClick()}
-calls {@code gcm.send()}, it triggers the broadcast receiver's {@code onReceive()}
-method, which has the responsibility of making sure that the GCM message gets handled.
    
+intent. A broadcast receiver is the mechanism GCM uses to deliver messages. 
    
 
    A {@link android.support.v4.content.WakefulBroadcastReceiver} is a special type of
 broadcast receiver that takes care of
 creating and managing a
@@ -646,6 +614,46 @@ public class GcmIntentService extends IntentService {
     }
 }
    
 
+
+
    Send an upstream message
    
+
    When the user clicks the app's Send button, the app sends an
+upstream message using the
+
+{@code GoogleCloudMessaging} API. In order to receive the upstream message,
+your server should be connected to CCS. You can use one of the demo servers in
+Implementing an XMPP-based App Server to run the sample and connect
+to CCS.
    
+
+
    public void onClick(final View view) {
+    if (view == findViewById(R.id.send)) {
+        new AsyncTask() {
+            @Override
+            protected String doInBackground(Void... params) {
+                String msg = "";
+                try {
+                    Bundle data = new Bundle();
+                        data.putString("my_message", "Hello World");
+                        data.putString("my_action",
+                                "com.google.android.gcm.demo.app.ECHO_NOW");
+                        String id = Integer.toString(msgId.incrementAndGet());
+                        gcm.send(SENDER_ID + "@gcm.googleapis.com", id, data);
+                        msg = "Sent message";
+                } catch (IOException ex) {
+                    msg = "Error :" + ex.getMessage();
+                }
+                return msg;
+            }
+
+            @Override
+            protected void onPostExecute(String msg) {
+                mDisplay.append(msg + "\n");
+            }
+        }.execute(null, null, null);
+    } else if (view == findViewById(R.id.clear)) {
+        mDisplay.setText("");
+    }
+}
    
+
 
    Running the Sample
    
 
 
    To run the sample:
    
diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd
index 3d6594d..4e345b3 100644
--- a/docs/html/google/gcm/gcm.jd
+++ b/docs/html/google/gcm/gcm.jd
@@ -9,58 +9,24 @@ page.title=Overview
 
      
   
    1. Key Concepts
      2. 
   
    2. Architectural Overview
      3. 
-  
    3. Lifecycle Flow
-    
        
-      
      1. Enable GCM
        2. 
-      
      2. Send a message
        3. 
-      
      3. Receive a message
        4. 
-    
      
-  
      4. 
+  
    4. Lifecycle Flow
      5. 
+  
    5. Register to enable GCM
      6. 
 
    
 
 
 
 
-
    Google Cloud Messaging (GCM) for Android is a free service that helps
-developers  send data from servers to their Android applications on  Android
-devices, and upstream messages from the user's device back to the cloud.
-This could be a lightweight message telling the Android application
+
    Google Cloud Messaging (GCM) is a free service that enables developers
+to send downstream messages (from servers to GCM-enabled client apps), and
+upstream messages (from the GCM-enabled client apps to servers).
+This could be a lightweight message telling the client app
 that there is new data to be fetched from the server (for instance, a "new email"
-notification informing the application that it is out of sync with the back end),
+notification informing the app that it is out of sync with the back end),
 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 Getting Started.
    
+service handles all aspects of queueing of messages and delivery to and from
+the target client app.
    
 
-
    Here are the primary characteristics of Google Cloud 
-Messaging (GCM):
    
-
-
      
-  
    • It allows 3rd-party application servers to send messages to
-their Android applications.
      • 
-  
    • Using the GCM Cloud Connection Server, you can receive
-upstream messages from the user's device.
      • 
-  
    • An Android application on an Android device doesn't need to be running to receive
-messages. The system will wake up the Android application via Intent broadcast
-when the  message arrives, as long as the application is set up with the proper
-broadcast receiver and permissions.
      • 
-  
    • It does not provide any  built-in user interface or other handling for
-message data. GCM  simply passes raw message data received straight to the
-Android application,  which has full control of how to handle it. For example, the
-application might post a notification, display a custom user interface, or 
-silently sync data.
      • 
-  
    • It requires devices running Android 2.2 or higher that also have the
-Google Play Store application installed, or or an emulator running Android 2.2
-with Google APIs. However, you are not limited to deploying your
-Android applications through Google Play Store.
      • 
-  
    • It uses an existing connection for Google services. For pre-3.0 devices,
-this requires users to
-set up their Google account on their mobile devices. A Google account is not a
-requirement on devices running Android 4.0.4 or higher.
      • 
-
    
 
 
    Key Concepts
    
 
@@ -70,7 +36,7 @@ divided into these categories:
    
   
  10. Components — The entities that play a primary role in
 GCM.
    11. 
   
  11. Credentials — The IDs and tokens that are used in
-different stages of GCM to ensure that all parties have been authenticated, and
+GCM to ensure that all parties have been authenticated, and
 that the message is going to the correct place.
    12. 
 
 
@@ -81,24 +47,20 @@ that the message is going to the correct place.
   
     Components
   
-  
-    Client App
-    The GCM-enabled Android application that is running on a
-    device. 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.
+
+    GCM Connection Servers
+    The Google-provided servers involved in sending messages between the
+3rd-party app server and the client app.
   
   
-    3rd-party Application Server
-    An application server that you write as part of implementing
-GCM. The 3rd-party application server sends data to an
-Android application on the device via the GCM connection server.
+    Client App
+    A GCM-enabled client app that communicates with a 3rd-party app server.
   
   
-    GCM Connection Servers
-    The Google-provided servers involved in taking messages from the 3rd-party
-application server and sending them to the device. 
+    3rd-party App Server
+    An app server that you write as part of implementing
+GCM. The 3rd-party app server sends data to a client app via
+the GCM connection server.
   
   
     Credentials
@@ -108,43 +70,29 @@ application server and sending them to the device. 
     A project number you acquire from the API console, as described in
 Getting Started. The sender
 ID is used in the registration process to identify a
-3rd-party application server that is permitted to send messages to the device.
+3rd-party app server that is permitted to send messages to the client app.
+  
+  
+    Sender Auth Token
+    An API key that is saved on the 3rd-party app
+server that gives the app server authorized access to Google services.
+The API key is included in the header of POST requests.
+
   
   
     Application ID
-    The Android application that is registering to receive messages. The Android application
+    The client app that is registering to receive messages. How this is implemented
+is platform-dependent. For example, an Android app
 is identified by the package name from the manifest.
-This  ensures that the messages are targeted to the correct Android application.
+This  ensures that the messages are targeted to the correct Android app.
   
   
     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. Note that registration IDs must be kept secret.
-
    
-
    
-Note: If you use 
-backup and restore,
-you should explicitly avoid backing up registration IDs. When you back up
-a device, apps back up shared prefs indiscriminately. If you don't explicitly
-exclude the GCM registration ID, it could get reused on a new device,
-which would cause delivery errors.
+    An ID issued by the GCM servers to the client app that allows
+it to receive messages. Note that registration IDs must be kept secret.
+
 
   
-  
-    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.
-  
 
 
 
@@ -152,7 +100,8 @@ The API key is included in the header of POST requests  that send messages.
 
 
    A GCM implementation includes a Google-provided
 connection server, a 3rd-party app server that interacts with the connection
-server, and a GCM-enabled client app running on an Android device:
    
+server, and a GCM-enabled client app. For example, this diagram shows GCM
+communicating with a client app on an Android device:
    
 
 
 
@@ -163,84 +112,196 @@ server, and a GCM-enabled client app running on an Android device:
    
 
    This is how these components interact:
    
 
      
   
    • Google-provided GCM Connection Servers take messages from
-a 3rd-party application server and send these messages to a
-GCM-enabled Android application (the "client app") running on a device.
+a 3rd-party app server and send these messages to a
+GCM-enabled client app (the "client app").
 Currently Google provides connection servers for HTTP
 and XMPP.
      • 
-  
    • The 3rd-Party Application Server is a component that you
+  
    • The 3rd-Party App Server is a component that you
 implement to work with your chosen GCM connection server(s). App servers send
 messages to a GCM connection server; the connection server enqueues and stores the
-message, and then sends it to the device when the device is online.
+message, and then sends it to the client app.
 For more information, see Implementing GCM Server.
      • 
-  
    • The Client App is a GCM-enabled Android application running
-on a device. To receive GCM messages, this app must register with GCM and get a
+  
    • The Client App is a GCM-enabled client app.
+To receive GCM messages, this app must register with GCM and get a
 registration ID. If you are using the XMPP (CCS) connection
-server, the client app can send "upstream" messages back to the connection server.
+server, the client app can send "upstream" messages back to the 3rd-party app server.
 For more information on how to implement the client app, see
-Implementing GCM Client.
      • 
+the documentation for your platform.
 
    
 
 
    Lifecycle Flow
    
 
 
      
-  
    • Enable GCM. An Android application running on a
-mobile device registers to receive messages.
      • 
+  
    • Register to enable GCM. A client app registers to receive messages.
+For more discussion, see Register to enable GCM.
      • 
+  
    • Send and receive downstream messages.
+  
        
+     
      • Send a message. A 3rd-party app server sends messages to the client app:
+       
          
+         
        1. The 3rd-party app server sends a message
+to GCM connection servers.
          2. 
+         
        2. The GCM connection server enqueues and stores the message if the device is offline.
          3. 
+         
        3. When the device is online, the GCM connection server sends the message to the device. 
          4. 
+         
        4. On the device, the client app receives the message according to the platform-specific implementation.
+See your platform-specific documentation for details.
          5. 
+       
        
+    
        • 
+  
      • Receive a message. A client app
+receives a message from a GCM server. See your platform-specific documentation for details
+on how a client app in that environment processes the messages it receives.
        • 
+  
      
+
      • 
+
+  
    • Send and receive upstream messages. This feature is only available if
+you're using the XMPP Cloud Connection Server (CCS).
+
        
+     
      • Send a message. A client app sends messages to the 3rd-party app server:
+      
          
+        
        1. On the device, the client app sends messages to XMPP (CCS).See your platform-specific
+          documentation for details on how a client app can send a message to XMPP (CCS).
          2. 
+        
        2. XMPP (CCS) enqueues and stores the message if the server is disconnected.
          3. 
+        
        3. When the 3rd-party app server is re-connected, XMPP (CCS) sends the message to the 3rd-party app server.
          4. 
+      
        
+    
        • 
+  
      • Receive a message. A 3rd-party app server receives a message from XMPP (CCS) and then does the following:
+      
          
+        
        1. Parses the message header to verify client app sender information.
+        
        2. Sends "ack" to GCM XMPP connection server to acknowledge receiving the message.
+        
        3. Optionally parses the message payload, as defined by the client app.
+      
        
+
        • 
+
      
+
+
      • 
+
 
-  
    • Send a message. A 3rd-party application
-server sends messages to the device.
      • 
-  
    • Receive a message. An Android application
-receives a message from a GCM server.
      • 
 
    
 
-
    These processes are described in more detail below.
    
+
    Register to enable GCM
    
+
+
    Regardless of the platform you're developing on, the first step
+a client app must do is register with GCM. This section covers some of the general
+best practices for registration and unregistration. See your platform-specific docs for
+details on writing a GCM-enabled client app on that platform.
    
 
-
    Enable GCM
    
+
    Keeping the Registration State in Sync
    
+
    Whenever the app registers as described in
+Implementing GCM Client,
+it should save the registration 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, the client app should retry passing the
+registration ID to 3rd-party app server to complete the registration.
+If this continues to fail, the client app should unregister from GCM.
    
 
-
    The first time the Android application needs to use the messaging service, it
-calls the 
-{@code GoogleCloudMessaging} method {@code register()}, as discussed in
-Implementing GCM Client.
-The {@code register()} method returns a registration ID. The Android
-application should store this ID for later use (for instance,
-to check in onCreate() if it is already registered).
+
    There are also two other scenarios that require special care:
    
+
      
+  
    • Client app update
      • 
+  
    • Backup and restore
+  
      • 
+
    
+
    Client app update: When a client app is updated, it should invalidate its existing registration
+ID, as it is not guaranteed to work with the new version.  The recommended way to achieve
+this validation is by storing the current app version when a registration
+ID is stored. Then when the app starts, compare the stored value with
+the current app version. If they do not match, invalidate the stored data
+and start the registration process again.
    
+
+
    Backup and restore:  You should not save the registration ID when an app is
+backed up. This is because the registration ID could become invalid by the time
+the app is restored, which would put the app in an invalid state
+(that is, the app thinks it is registered, but the server and GCM do not
+store that registration ID anymore—thus the app will not get more
+messages). The best practice is to initiate the registration process as if the app has been
+installed for the first time.
    
+
+
    Canonical IDs
    
+
    If a bug in the app 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 app. 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.
    
+
+
    Automatic Retry Using Exponential Back-Off
    
+
+
    When registration or unregistration fails, the app should retry the failed operation.
    
+
    In the simplest case, if your app attempts to register and GCM is not a
+fundamental part of the app, the app 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.
 
    
 
-
    Send a message
    
+
    Unregistration
    
 
-
    Here is the sequence of events that occurs when the application server sends a 
-message:
    
+
    This section explains when you should unregister in GCM and what happens
+when you do.
    
 
-
      
-  
    1. The application server sends a  message to  GCM servers.
      2. 
-  
    2. Google enqueues and stores the message in case the device is
-offline.
      3. 
-  
    3. When the device is online, Google sends the message to the device. 
      4. 
-  
    4. On the device, the system  broadcasts the  message to the specified
-Android application via Intent broadcast with proper permissions, so that only the
-targeted Android application gets the message. This wakes the Android application up. The
-Android application does not need to be running beforehand to receive the message.
      5. 
-  
    5. The Android application processes the message. If the Android application is doing
-non-trivial processing, you may want to grab a
-{@link android.os.PowerManager.WakeLock} and do any processing in a service.
      6. 
-
    
+
    Why you should rarely unregister
    
+
+
    You should only need to unregister in rare cases, such as
+if you want an app to stop receiving messages, or if you suspect that the registration ID has
+been compromised. In general, once an app has a registration ID, you shouldn't need
+to change it.
    
 
-
     An Android application can  unregister GCM if it no longer wants to receive 
-messages.
    
+
    In particular, you should never unregister your app as a mechanism for
+logout or for switching between users, for the following reasons:
    
+
+
      
+  
    • A registration ID isn't associated with a particular
+  logged in user. If you unregister and then re-register, GCM may return the same
+  ID or a different ID—there's no guarantee either way.
      • 
+
+  
    • Unregistration may take up to 5 minutes to propagate.
      • 
+  
    • After unregistration, re-registration may again take up to 5 minutes to
+propagate. During this time messages may be rejected due to the state of being
+unregistered, and after all this, messages may still go to the wrong user.
      • 
+
    
 
-
    Receive a message
    
 
-
    This is the sequence of events that occurs when an Android application
-installed on a mobile device receives a message:
    
+
    To make sure that messages go to the intended user:
    
 
+
      
+  
    • Your app server can maintain a mapping between the current user
+and the registration ID.
      • 
+  
    • The app can then check to ensure that messages it
+receives match the logged in user.
      • 
+
    
+
+
+
    How unregistration works
    
+
+
    An app can be automatically unregistered after it is uninstalled.
+However, this process does not happen right away. What happens in
+this scenario is as follows:
    
 
      
-  
    1. The system receives the incoming message and extracts the raw key/value
-pairs from the message payload, if any.
      2. 
-  
    2. The system passes the key/value pairs to the targeted Android application
-in a com.google.android.c2dm.intent.RECEIVE Intent as a set of
-extras.
      3. 
-  
    3. The Android application extracts the raw data
-from the com.google.android.c2dm.intent.RECEIVE Intent
-by key and processes the data.
      4. 
+  
    4. The end user uninstalls the client app.
      5. 
+  
    5. The 3rd-party app server sends a message to GCM server.
      6. 
+  
    6. The GCM server sends the message to the GCM client on the device.
      7. 
+  
    7. The GCM client on the device receives the message and detects that the client app has been
+   uninstalled; the detection details depend on the platform on which the client app is running.
+
      8. 
+  
    8. The GCM client on the device informs the GCM server that the client app was uninstalled.
      9. 
+  
    9. The GCM server marks the registration ID for deletion.
      10. 
+  
    10. The 3rd-party app server sends a message to  GCM.
      11. 
+  
    11. The GCM returns a NotRegistered error message to the 3rd-party app server.
      12. 
+  
    12. The 3rd-party app server deletes the registration ID.
+  
      13. 
 
    
 
+
    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 client app.
+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 app is
+being developed and tested).
    
 
diff --git a/docs/html/google/gcm/gs.jd b/docs/html/google/gcm/gs.jd
index a889624..2331292 100644
--- a/docs/html/google/gcm/gs.jd
+++ b/docs/html/google/gcm/gs.jd
@@ -1,4 +1,4 @@
-page.title=Getting Started
+page.title=Getting Started on Android
 page.tags=cloud,push,messaging
 @jd:body
 
@@ -46,7 +46,7 @@ project number. For example, Project Number: 670330094152.
    <
 
   
  12. Copy down your project number. You will use it later on as the
   GCM sender ID.
    13. 
-  
+

Enabling the GCM Service

To enable the GCM service:

@@ -71,7 +71,7 @@ purposes, you can use {@code 0.0.0.0/0}.

  • In the refreshed page, copy the API key. -You will need the API key later on to perform authentication in your application server.
    • +You will need the API key later on to perform authentication in your app server.

    Note: If you need to rotate the key, click Regenerate key. A new key will be created. If you think the key has been @@ -84,16 +84,11 @@ compromised and you want to delete it immediately, click Delete implementing GCM. Here is an overview of the basic steps:

      -
    1. Decide which Google-provided GCM connection server you want to use— - HTTP or XMPP (CCS). GCM connection servers -take messages from a 3rd-party application -server (written by you) and send them to a GCM-enabled Android application (the -"client app," also written by you) running on a device.
      2. -
    2. Implement an application server (the "3rd-party application server") to interact +
    3. Implement an app server (the "3rd-party app server") to interact with your chosen GCM connection server. The app server sends data to a -GCM-enabled Android client application via the GCM connection server. For more +GCM-enabled Android client app via the GCM connection server. For more information about implementing the server side, see Implementing GCM Server.
      4. -
    4. Write your client app. This is the GCM-enabled Android application that runs +
    5. Write your client app. This is the GCM-enabled Android app that runs on a device. See Implementing GCM Client for more information.
    diff --git a/docs/html/google/gcm/http.jd b/docs/html/google/gcm/http.jd index 773acd1..5022e09 100644 --- a/docs/html/google/gcm/http.jd +++ b/docs/html/google/gcm/http.jd @@ -23,6 +23,7 @@ page.title=GCM HTTP Connection Server

    See Also

      +
    1. Server Reference
    2. Getting Started
    3. Implementing GCM Client
    4. Cloud Connection Server
      5. @@ -42,26 +43,30 @@ application server and sending them to the device.

      applies to GCM with Chrome apps as well as Android.

      -

      See -Implementing GCM Server for a list of all the message +

      See the +Server Reference for a list of all the message parameters and which connection server(s) supports them.

      Authentication

      -

      To send a message, the application server issues a POST request to -https://android.googleapis.com/gcm/send.

      +

      To send a message, the application server issues a POST request. For example:

      +
      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:

      For example:

      + 
      Content-Type:application/json
 Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA
 
@@ -71,26 +76,30 @@ Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA
     ...
   },
 }
      -

      -

      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. See -Implementing GCM Server for a list of all the +the Server Reference for a list of all the parameters your JSON or plain text message can contain.

      Request Format

      + +

      This section shows you how to format a request for both JSON and plain text. See +the Server Reference for a complete +list of the fields you can include in a request.

      +

      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"
@@ -112,10 +121,25 @@ just one recipient) using JSON:
      
   
      collapse_key=score_update&time_to_live=108&delay_while_idle=1&data.score=4x8&data.time=15:16.2342&registration_id=42
   
      
 
+
      Here is a message that includes a notification key and payload:
      
+
+
      +{
+  "data": {
+    "message": "ciao"
+  },
+  "notification_key":"aUniqueKey"
+}
+
      
+
+
      For more information about notifications and how to use them, see
+User Notifications.
      
+
+
 
      Note: If your organization has a firewall
 that restricts the traffic to or
 from the Internet, you need to configure it to allow connectivity with GCM in order for
-your Android devices to receive messages.
+your GCM client apps to receive messages.
 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, so you should allow
 your firewall to accept outgoing connections to all IP addresses
@@ -127,54 +151,12 @@ contained in the IP blocks listed in Google's ASN of 15169.
      
 
 
      There are two possible outcomes when trying to send a message:
      
 
        
-  
      • The message is processed successfully.
        • 
-  
      • The GCM server rejects the request.
        • 
+  
      • The message 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).
        • 
+  
      • The GCM server rejects the request. The HTTP response contains a
+non-200 status code (such as 400, 401 or 5xx).
        • 
 
      
 
-
      When the message 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.
      
-
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-
      ResponseDescription
      200Message 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.
      400Only 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.
      401There was an error authenticating the sender account.
-Troubleshoot
      5xxErrors in the 500-599 range (such as 500 or 503) indicate that there was
-an internal error in the GCM server while trying to process the request, or that
-the server is temporarily unavailable (for example, because of timeouts). Sender
-must retry later, honoring any Retry-After header included in the
-response. Application servers must implement exponential back-off.
-Troubleshoot
      
-
 
      Interpreting a success response
      
 
      When a JSON request is successful (HTTP status code 200), the response body
 contains a JSON object with the following fields:
      
@@ -241,8 +223,8 @@ code>registration_ids passed in the request (using the same index).
 request.
       
    5. If it is NotRegistered, you should remove the registration
 ID from your server database because the application was uninstalled from the
-device or it does not have a broadcast receiver configured to receive
-com.google.android.c2dm.intent.RECEIVE intents.
      6. 
+device, or the client app isn't configured to receive
+messages.
       
    6. Otherwise, there is something wrong in the registration ID passed in
 the request; it is probably a non-recoverable error that will also require removing
 the registration from the server database. See Interpreting
@@ -291,8 +273,7 @@ might occur when trying to send a message to a device:
      
 
 
      Invalid Registration ID
      
 
      Check the formatting of the registration ID that you pass to the server. Make
-sure it matches the registration ID the phone receives in the
-com.google.android.c2dm.intent.REGISTRATION intent and that you're
+sure it matches the registration ID the client app receives and that you're
 not truncating it or adding additional characters.
 
      Happens when error code is InvalidRegistration.
      
 
@@ -306,17 +287,13 @@ Happens when error code is MismatchSenderId.
 
      Unregistered Device
      
 
      An existing registration ID may cease to be valid in a number of scenarios, including:
 
        
-  
      • If the application manually unregisters by issuing a
-
-com.google.android.c2dm.intent.UNREGISTER
-intent.
        • 
+  
      • If the application manually unregisters.
        • 
   
      • If the application is automatically unregistered, which can happen
 (but is not guaranteed) if the user uninstalls the application.
        • 
   
      • If the registration ID expires. Google might decide to refresh registration
 IDs. 
        • 
-  
      • If the application is updated but the new version does not have a broadcast
-receiver configured to receive com.google.android.c2dm.intent.RECEIVE
-intents.
        • 
+  
      • If the application is updated but the new version is not configured to receive
+messages.
        • 
 
      
 For all these cases, you should remove this registration ID from the 3rd-party
 server and stop using it to send
@@ -331,8 +308,7 @@ as the values.
 
 
      Invalid Data Key
      
 
      The payload data contains a key (such as from or any value
-prefixed by google.) that is used internally by GCM in the
-com.google.android.c2dm.intent.RECEIVE Intent and cannot be used.
+prefixed by google.) that is used internally by GCM and therefore cannot be used.
 Note that some words (such as collapse_key) are also used by GCM
 but are allowed in the payload, in which case the payload value will be
 overridden by the GCM value.
@@ -354,9 +330,9 @@ authenticated. Possible causes are: 
        
 
      • Request originated from a server not whitelisted in the Server Key IPs.
        • 
 
 
      
-Check that the token you're sending inside the Authorization header
-is the correct API key associated with your project. You can check the validity
-of your API key by running the following command:
      
+When there is an Authentication Error, you can check the validity of your API key by running You can check the validity
+of your API key by running the following command (this example shows what you
+would do on Android; see the documentation for your platform):
      
 
 
      # api_key=YOUR_API_KEY
 
@@ -405,8 +381,7 @@ Happens when the HTTP status code is between 501 and 599, or when the
 
      
 The server encountered an error while trying to process the request. You
 could retry the same request (obeying the requirements listed in the Timeout
-section), but if the error persists, please report the problem in the
-android-gcm group.
+section), but if the error persists, please report the problem to Google.
 
      
 Happens when the HTTP status code is 500, or when the error field of a JSON
 object in the results array is InternalServerError.
@@ -488,7 +463,7 @@ registration_id=32
 
 
      This section gives examples of implementing an app server that works with the
 GCM HTTP connection server. Note that a full GCM implementation requires a
-client-side implementation, in addition to the server.
+client-side implementation, in addition to the server. This example is based on Android.
 
 
 
      Requirements
      
@@ -508,7 +483,7 @@ version 1.6 or later.
      7. 
 
 
      For the Android application:
      
 
        
-  
      • Emulator (or device) running Android 2.2 with Google APIs.
        • 
+  
      • Emulator (or device) running Android 2.2 (ideally, 2.3 or above) with Google APIs.
        • 
   
      • The Google API project number of the account registered to use GCM.
        • 
 
      
 
diff --git a/docs/html/google/gcm/notifications.jd b/docs/html/google/gcm/notifications.jd
index 147b69c..333d4b6 100644
--- a/docs/html/google/gcm/notifications.jd
+++ b/docs/html/google/gcm/notifications.jd
@@ -306,9 +306,3 @@ receive the message:
      
 
      In the case of failure, the response has HTTP code 503 and no JSON. When a message
 fails to be delivered to one or more of the regIDs associated with a {@code notification_key},
 the 3rd-party server should retry.
      
-
-
-
-
-
-
diff --git a/docs/html/google/gcm/server-ref.jd b/docs/html/google/gcm/server-ref.jd
new file mode 100644
index 0000000..a94e727
--- /dev/null
+++ b/docs/html/google/gcm/server-ref.jd
@@ -0,0 +1,763 @@
+page.title=Server Reference
+@jd:body
+
+
+
+
      This document provides a reference for the syntax used to pass
+messages back and forth in GCM. These messages fall into
+the following broad categories:
      
+
+
+
+
      The following sections describe the basic requirements for
+sending messages.
      
+
+
      Downstream Messages
      
+
      This is the message that a 3rd-party app server sends to a client app.
+
      
+
      A downstream message includes the following components:
      
+
        
+  
      • Target: specifies the recipient of the message.
        • 
+  
      • Options: specifies attributes of the message.
        • 
+  
      • Payload: specifies additional content to be included in the message. Optional.
        • 
+
      
+
+
      The syntax for each of these components is described in the tables below. 
      
+
+
      Sending a downstream message
      
+
+
      This section gives the syntax for sending a downstream messages. For JSON,
+these messages can be either HTTP or XMPP. For plain text, these messages can only be HTTP.
      
+
+
      Downstream HTTP or XMPP messages (JSON)
      
+
+
      The following table lists the targets, options, and payload for HTTP or XMPP JSON messages.
      
+
      
+  Table 1. Targets, options, and payload for downstream HTTP or XMPP message (JSON).
      
+
+  
+    
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+    
+  
+
      ParameterProtocolUsageDescription
      Targets
      toXMPPRequired, string
      This parameter specifies the recipient of a message. 
      
+      
      The value must be a registration ID or notification key.
      
+    
      This parameter is used in XMPP in place of {@code registration_ids} or   {@code notification_key} in HTTP.
      registration_idsHTTPRequired if {@code notification_key} not present, string array
      This parameter specifies the list of devices (registration IDs)
+receiving the message. It must contain at least 1 and at most 1000 registration IDs.
      
+      
      Multicast messages (sending to more than 1 registration IDs) are allowed using HTTP JSON format only.
      
+    
      This parameter or {@code notification_key} is used in HTTP in place of {@code to} in XMPP.
      notification_keyHTTPRequired if {@code registration_ids} not present, string
      This parameter specifies the mapping of a single user to
+multiple registration IDs associated with that user.
      
+      
      This allows a 3rd-party app server to send a single message to multiple app instances
+(typically on multiple devices) owned by a single user.
      
+      
      A 3rd-party app server can use {@code notification_key} as the target for a
+message instead of an individual registration ID (or array of registration IDs).
+The maximum number of members allowed for a {@code notification_key} is 20.
      
+      
      This parameter or {@code registration_ids} is used in HTTP in place of {@code to} in XMPP.
      
+    
      See User Notifications for details.
      Options
      message_idXMPPRequired, string
      This parameter uniquely identifies a message in an XMPP connection.
      collapse_keyHTTP, XMPPOptional, string
      This parameters identifies a group of messages (e.g., with
+{@code collapse_key: "Updates Available"}) that can be collapsed, so that only the
+last message gets sent when delivery can be resumed. This is intended to avoid sending too
+many of the same messages when the device comes back online or becomes active (see {@code delay_while_idle}).
      
+      
      Note that there is no guarantee of the order in which messages get sent.
      
+      
      Messages with collapse key are also called
+send-to-sync messages messages.
+
      
+    
      Note: A maximum of 4 different collapse keys is allowed at any given time. This means a
+GCM connection server can simultaneously store 4 different send-to-sync messages per client app. If you
+exceed this number, there is no guarantee which 4 collapse keys the GCM connection server will keep. 
      delay_while_idleHTTP, XMPPOptional, JSON booleanWhen this parameter is set to {@code true}, it indicates that the message should not be
+sent until the device becomes active.
      
+    
      The default value is {@code false}.
      time_to_liveHTTP, XMPPOptional, JSON number
      This parameter specifies how long (in seconds) the message should be kept in GCM storage
+if the device is offline. The maximum time to live supported is 4 weeks.
      
+    
      The default value is 4 weeks. 
      delivery_receipt_
+
      requested      		XMPPOptional, JSON boolean
      This parameter lets 3rd-party app server request confirmation of message delivery.
      
+      
      When this parameter is set to {@code true}, CCS sends a delivery receipt
+when the device confirms that it received the message.
      
+    
      The default value is {@code false}.
      restricted_package_
+
      name      		HTTPOptional, stringThis parameter specifies the package name of the application where the
+registration IDs must match in order to receive the message.
      dry_runHTTPOptional, JSON boolean
      This parameter, when set to {@code true}, allows developers to test a
+request without actually sending a message.
      
+    
      The default value is {@code false}.
      Payload
      dataHTTP, XMPPOptional, JSON object
      This parameter specifies the key-value pairs of the message's payload. There is
+no limit on the number of key-value pairs, but there is a total message size limit of 4kb.
      
+      
      For instance, in Android, data:{"score":"3x1"} would result in an intent extra
+named {@code score} with the string value {@code 3x1}.
      
+      
      The key should not be a reserved word ({@code from} or any word starting with
+{@code google}). It is also not recommended to use words defined in this table
+(such as {@code collapse_key}) because that could yield unpredictable outcomes. 
      
+    
      Values in string types are recommended. You have to convert values in objects
+or other non-string data types (e.g., integers or booleans) to string.
      
+
+
      Downstream HTTP messages (Plain Text)
      
+
+
      The following table lists the syntax for targets, options, and payload in plain
+text downstream HTTP messages.
      
+
+
      
+  Table 2. Targets, options, and payload for downstream plain text HTTP messages.
      
+
+
+  
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      Targets
      registration _idRequired, string
      This parameter specifies the client apps (registration ID) receiving the message.
      
+    
      Multicast messaging (sending to more than one registration ID) is allowed using HTTP JSON format only.
      Options
      collapse_keyOptional, stringSee table 1 for details.
      delay_while_idleOptional, boolean or numberSee table 1 for details.
      time_to_liveOptional, numberSee table 1 for details.
      restricted_package_nameOptional, stringSee table 1 for details.
      dry_run Optional, booleanSee table 1 for details.
      Payload
      data.<key>Optional, string
      This parameter specifies the key-value pairs of the message's payload.
+There is no limit on the number of key-value parameters,
+but there is a total message size limit of 4kb.
      
+      
      For instance, in Android, data:{"score":"3x1"} would result in an intent extra
+named {@code score} with the string value {@code 3x1}.
      
+    
      The key should not be a reserved word ({@code from} or any word starting with
+{@code google}). It is also not recommended to use words defined in this table
+(such as {@code collapse_key}) because that could yield unpredictable outcomes.
      
+
+
      Interpreting a Downstream Message Response
      
+
+
      This section describes the syntax of a response to a downstream message. A client
+app or the GCM Connection Server sends the response to 3rd-party app server upon processing
+the message request. 
      
+
+
      Interpreting a downstream HTTP message response 
      
+
      The 3rd-party app server should look at both the message response header and the body
+to interpret the message response sent from the GCM Connection Server. The following table
+describes the possible responses.
      
+
      
+
+
      
+  Table 3. Downstream HTTP message response header.
      
+
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+    
+  
+
      ResponseDescription
      200Message 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 table 4
+for more details.
      400Only 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.
      401There was an error authenticating the sender account.
+Troubleshoot
      5xxErrors in the 500-599 range (such as 500 or 503) indicate that there was
+an internal error in the GCM server while trying to process the request, or that
+the server is temporarily unavailable (for example, because of timeouts). Sender
+must retry later, honoring any Retry-After header included in the
+response. Application servers must implement exponential back-off.
+Troubleshoot
      
+
+
      The following table lists the fields in a downstream message response body
+(JSON).
      
+
+
+
      
+  Table 4. Downstream HTTP message response body (JSON).
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      multicast_idRequired, numberUnique ID (number) identifying the multicast message.
      successRequired, numberNumber of messages that were processed without an error.
      failureRequired, numberNumber of messages that could not be processed.
      canonical_idsRequired, numberNumber of results that contain a canonical registration ID. See the
+Overview for more discussion of this topic.
      resultsOptional, array objectArray 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).
      
+      
        
+        
      • message_id: String specifying a unique ID for each successfully processed
+          message.
        • 
+        
      • registration_id: Optional string specifying the canonical registration ID
+          for the client app that the message was processed and sent to. Sender should use this
+          value as the Registration ID for future requests. Otherwise, the messages might
+          be rejected.
+        
        • 
+        
      • error: String specifying the error that occurred when processing the
+          message for the recipient. The possible values can be found in table 11
+        .
        • 
+    
      
+
+
+
      
+  Table 5. Success response for downstream HTTP message response body (Plain Text).
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      idRequired, stringThis parameter specifies the unique message ID that GCM server processed successfully.
      registration_idOptional, stringThis parameter specifies the canonical registration ID for the client app that the message was
+processed and sent to. Sender should replace the registration ID with this value on future requests,
+otherwise, the messages might be rejected.
      
+
+
      
+  Table 6. Error response for downstream HTTP message response body (Plain Text).
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      {@code Error}Required, stringThis parameter specifies the error value while processing the message for the recipient.
+See table 11 for details. 
      
+
+
      Interpreting a downstream XMPP message response
      
+
+
      The following table lists the fields that appear in a downstream XMPP message response.
      
+
+
      
+  Table 7. Downstream message XMPP message response body.
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      fromRequired, string
      This parameter specifies who sent this response.
      
+    
      The value is the registration ID of the client app.
      message_idRequired, stringThis parameter uniquely identifies a message in an XMPP connection.
+The value is a string that uniquely identifies the associated message.
      message_typeRequired, string
      This parameter specifies an 'ack' or 'nack' message from XMPP (CCS)
+to the 3rd-party app server.
      
+    
      If the value is set to {@code nack}, the 3rd-party app server should look at
+{@code error} and {@code error_description} to get failure information. 
      errorOptional, stringThis parameter specifies an error related to the downstream message. It is set when the
+{@code message_type} is {@code nack}. See table 6 for details.
      error_descriptionOptional, stringThis parameter provides descriptive information for the error. It is set
+when the {@code message_type} is {@code nack}.
      
+
      Upstream Messages (XMPP)
      
+
+
      An upstream message is a message the client app sends to the 3rd-party app server.
+Currently only CCS (XMPP) supports upstream messaging.
      
+
+
      Interpreting an upstream XMPP message 
      
+
      The following table describes the fields that appear in an upstream XMPP message.
+
+
      
+  Table 8. Upstream XMPP messages.
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      fromRequired, string
      This parameter specifies who sent the message.
      
+    
      The value is the registration ID of the client app.
      categoryRequired, stringThis parameter specifies the application package name of the client app that sent the message. 
      message_idRequired, stringThis parameter specifies the unique ID of the message. 
      dataOptional, stringThis parameter specifies the key-value pairs of the message's payload.
      
+
+
      Sending an upstream XMPP message response
      
+
+
      The following table describes the response that 3rd-party app server is expected to send to
+XMPP (CCS) in response to an
+upstream message it (the app server) received.
      
+
+
      
+  Table 9. Upstream XMPP message response.
      
+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      toRequired, string
      This parameter specifies the recipient of a response message. 
      
+    
      The value must be a registration ID of the client app that sent the upstream message.
      message_idRequired, stringThis parameter specifies which message the response is intended for. The value must be
+the {@code message_id} value from the corresponding upstream message.
      message_typeRequired, stringThis parameter specifies an {@code ack} message from a 3rd-party app server to CCS.
      
+
      Cloud Connection Server Messages (XMPP) 
      
+
      This is a message sent from XMPP (CCS) to a 3rd-party app server. Here are the primary types
+of messages that XMPP (CCS) sends to the 3rd-party app server:
      
+
        
+  
      • Delivery Receipt: If the 3rd-party app server included {@code delivery_receipt_requested}
+in the downstream message, XMPP (CCS) sends a delivery receipt when it receives confirmation
+that the device received the message.
        • 
+  
      • Control: These CCS-generated messages indicate that
+action is required from the 3rd-party app server.
        • 
+
      
+
+
      The following table describes the fields included in the messages CCS
+sends to a 3rd-party app server.
      
+
+
      
+  Table 10. GCM Cloud Connection Server messages (XMPP).
      
+
+  
+    
+    
+    
+  
+  
+    
+  
+  
+    
+    
+    
+  
+  
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+  
+  
+    
+    
+    
+  
+
      ParameterUsageDescription
      Common Field
      message_typeRequired, string
      This parameter specifies the type of the CCS message: either delivery receipt or control.
      
+      
      When it is set to {@code receipt}, the message includes {@code from}, {@code message_id},
+        {@code category} and {@code data} fields to provide additional information.
      
+    
      When it is set to {@code control}, the message includes {@code control_type} to indicate the
+type of control message.
      Delivery receipt-specific
      fromRequired, stringThis parameter is set to {@code gcm.googleapis.com}, indicating that the
+message is sent from CCS.
      message_idRequired, stringThis parameter specifies the original message ID that the receipt is intended for,
+prefixed with {@code dr2:} to indicate that the message is a delivery receipt. A 3rd-party app
+server must send an {@code ack} message with this message ID to acknowledge that it
+received this delivery receipt. See table 9 for the 'ack' message format.
      categoryOptional, stringThis parameter specifies the application package name of the client app that
+receives the message that this delivery receipt is reporting. This is available when
+{@code message_type} is {@code receipt}.
      dataOptional, stringThis parameter specifies the key-value pairs for the delivery receipt message. This is available
+when the {@code message_type} is {@code receipt}.
+      
        
+        
      • {@code message_status}: This parameter specifies the status of the receipt message.
+It is set to {@code MESSAGE_SENT_TO_DEVICE} to indicate the device has confirmed its receipt of
+the original message.
        • 
+      
      • {@code original_message_id}: This parameter specifies the ID of the original message
+that the 3rd-party app server sent to the client app.
        • 
+     
      • {@code device_registration_id}: This parameter specifies the registration ID of the
+client app to which the original message was sent.
        • 
+    
      
+
      Control-specific
      control_typeOptional, string
      This parameter specifies the type of control message sent from CCS.
      
+    
      Currently, only {@code CONNECTION_DRAINING} is supported. XMPP (CCS) sends this control message
+before it closes a connection to perform load balancing. As the connection drains, no more messages
+are allowed to be sent to the connection, but existing messages in the pipeline will
+continue to be processed.
      
+
+
      Downstream message error response codes (HTTP and XMPP)
      
+
+
      The following table lists the error response codes for downstream messages (HTTP and XMPP).
      
+
+
      
+  Table 11. Downstream message error response codes.
      
+
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
      ErrorHTTP CodeXMPP CodeRecommended Action
      Missing Registration ID200 + error:MissingRegistrationINVALID_JSONCheck that the request contains a registration ID (either in the
+{@code registration_id} in a plain text message, or in the {@code registration_ids} in JSON).
      Invalid Registration ID200 + error:InvalidRegistrationBAD_REGISTRATIONCheck the format of the registration ID you pass to the server. Make sure it
+matches the registration ID the client app receives from registering with GCM. Do not
+truncate or add additional characters.
      Unregistered Device200 + error:NotRegisteredDEVICE_UNREGISTEREDAn existing registration ID may cease to be valid in a number of scenarios, including:
      
+     
        
+      
      • If the client app unregisters with GCM.
        • 
+      
      • If the client app is automatically unregistered, which can happen if the user uninstalls the application.
        • 
+      
      • If the registration ID expires (for example, Google might decide to refresh registration IDs).
        • 
+      
      • If the client app is updated but the new version is not configured to receive messages.
        • 
+
      
+ For all these cases, remove this registration ID from the 3rd-party app
+server and stop using it to send messages.
      Invalid Package Name200 + error:InvalidPackageNameMake sure the message was addressed to a registration ID whose package name
+matches the value passed in the request.
      Authentication Error401 The sender account used to send a message couldn't be authenticated. Possible causes are:
      
+
        
+      
      • Authorization header missing or with invalid syntax in HTTP request.
        • 
+      
      • Invalid project number sent as key.
        • 
+      
      • Key valid but with GCM service disabled.
        • 
+      
      • Request originated from a server not whitelisted in the Server Key IPs.
        • 
+
      
+    Check that the token you're sending inside the Authentication header is
+the correct API key associated with your project. See
+GCM HTTP Connection Server for details.
      Mismatched Sender200 + error:MismatchSenderIdBAD_REGISTRATIONA registration ID is tied to a certain group of senders. When a client app registers
+for GCM, it must specify which senders are allowed to send messages. You should use one
+of those sender IDs when sending messages to the client app. If you switch to a different
+sender, the existing registration IDs won't work.
      Invalid JSON400INVALID_JSONCheck that the JSON message is properly formatted and contains valid fields
+(for instance, making sure the right data type is passed in).
      Message Too Big200 + error:MessageTooBigINVALID_JSONCheck that the total size of the payload data included in a message does
+not exceed 4096 bytes. This includes both the the keys and the values.
      Invalid Data Key200 + error:
+
      
+InvalidDataKey      		INVALID_JSONCheck that the payload data does not contain a key (such as {@code from} or any value
+prefixed by {@code google}) that is used internally by GCM. Note that some words (such as {@code collapse_key})
+are also used by GCM but are allowed in the payload, in which case the payload value
+will be overridden by the GCM value.
      Invalid Time to Live200 + error:InvalidTtlINVALID_JSONCheck that the value used in {@code time_to_live} is an integer representing a
+duration in seconds between 0 and 2,419,200 (4 weeks).
      Bad ACK messageN/ABAD_ACKCheck that the 'ack' message is properly formatted before retrying. See
+table 9 for details.
      Timeout5xx or 200 + error:UnavailableSERVICE_UNAVAILABLE
      The server couldn't process the request in time. Retry the same request, but you must:
      
+
        
+      
      • For HTTP: Honor the {@code Retry-After} header if it is included in the response from the
+GCM Connection Server.
        • 
+      
      • Implement exponential back-off in your retry mechanism. (e.g. if you waited one second
+before the first retry, wait at least two second before the next one, then 4 seconds and so on).
+If you're sending multiple messages, delay each one independently by an additional random amount
+to avoid issuing a new request for all messages at the same time.
        • 
+    
      • For CCS: The initial retry delay should be set to 1 second.
        • 
+
      
+    
      Senders that cause problems risk being blacklisted.
      Internal Server Error500 or 200 + error:InternalServerErrorINTERNAL_SERVER_
+
      
+ERROR      		The server encountered an error while trying to process the request. You could retry
+the same request following the requirements listed in "Timeout" (see row above). If the error persists, please
+report the problem in the {@code android-gcm group}.
      Device Message Rate Exceeded200 + error:
+
      DeviceMessageRate
+
      
+Exceeded      		DEVICE_MESSAGE_RATE
      
+_EXCEEDED      		The rate of messages to a particular device is too high. Reduce the
+number of messages sent to this device and do not immediately retry sending to this device.
      Connection DrainingN/ACONNECTION_DRAININGThe message couldn't be processed because the connection is draining. This happens because
+periodically, XMPP (CCS) needs to close down a connection to perform load balancing. Retry the message over
+another XMPP connection.
      
diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd
index 20e2b2e..004fd0e 100644
--- a/docs/html/google/gcm/server.jd
+++ b/docs/html/google/gcm/server.jd
@@ -7,9 +7,9 @@ page.title=Implementing GCM Server
 
      In this document
      
 
 
        
-  
      1. Choosing a GCM Connection Server
        2. 
   
      2. Role of the 3rd-party Application Server
        3. 
-    
      3. Sending Messages
+  
      4. Choosing a GCM Connection Server
        5. 
+  
      5. Sending Messages
     
          
 
       
        1. Target
          2. 
@@ -17,7 +17,18 @@ page.title=Implementing GCM Server
       
        2. Message parameters
     
        
     
        6. 
-  
      6. Receiving Messages 
        7. 
+  
      7. Messaging Concepts and Best Practices
+
+   
          
+
+      
        1. Send-to-Sync vs. Messages with Payload
          2. 
+      
        2. Setting an Expiration Date for a Message
          3. 
+      
        3. Receiving Messages from Multiple Senders
+      
        4. Lifetime of a Message
+      
        5. Throttling
+    
        
+
+
        8. 
   
 
 
      
@@ -25,6 +36,7 @@ page.title=Implementing GCM Server
 
      See Also
      
 
 
        
+
      1. Server Reference
        2. 
 
      2. Getting Started
        3. 
 
      3. Implementing GCM Client
        4. 
 
      4. Cloud Connection Server (XMPP)
        5. 
@@ -37,388 +49,392 @@ page.title=Implementing GCM Server
 
 
 
-
        The server side of Google Cloud Messaging (GCM) consists of 2 components:
        
+
        The server side of Google Cloud Messaging (GCM) consists of two components:
        
 
          
 
        • Google-provided GCM Connection Servers
-take messages from a 3rd-party application server and send them to a GCM-enabled
-Android application (the "client app") running on a device. For example,
+take messages from a 3rd-party app server
+and send them to a GCM-enabled
+application (the "client app") running on a device. For example,
 Google provides connection servers for 
-HTTP and CCS (XMPP).
          • 
+HTTP and XMPP (CCS) (XMPP).
 
        • A 3rd-party application server that you must implement. This application
-server sends data to a GCM-enabled Android application via the chosen GCM connection server.
          • 
+server sends data to a GCM-enabled client app via the chosen GCM connection server.
 
        
 
        
 
+
        A full GCM implementation requires both a client implementation and a server
+implementation. For more
+information about implementing the client side, see 
+Implementing GCM Client.
        
+
+
+
        Role of the 3rd-party Application Server
        
+
+
        Before you can write client apps that use the GCM feature, you must
+have an  application server that meets the following criteria:
        
+
+
          
+  
        • Able to communicate with your client.
          • 
+  
        • Able to  fire off properly formatted requests to the GCM server.
          • 
+  
        • Able to handle requests and resend them as needed, using
+exponential back-off.
          • 
+  
        • Able to store the API key and client registration IDs. In HTTP, the API key is
+included in the header of POST requests that send messages. In XMPP, the API key is
+used in the SASL PLAIN authentication request as a password to authenticate the connection.
          • 
+ 
        • Able to generate message IDs to uniquely identify each message it sends. Message IDs
+should be unique per sender ID.
          • 
+
        
+
 
        Here are the basic steps you follow to implement your 3rd-party app server:
        
 
 
          
       
        • Decide which GCM connection server(s) you want to use. Note that if you want to use
-      upstream messaging from your client applications, you must use CCS. For a more detailed
+      upstream messaging from your client applications, you must use XMPP (CCS). For a more detailed
       discussion of this, see 
       Choosing a GCM Connection Server.
          • 
-      
        • Decide how you want to implement your app server. For example:
+      
        • Decide how you want to implement your app server. We provide helper libraries and code
+samples to assist you with your 3rd-party app server implementation. For example:
         
            
           
          • If you decide to use the HTTP connection server, you can use the
 GCM server helper library and demo app to help in implementing your app server.
            • 
           
          • If you decide to use the XMPP connection server, you can use
 the provided Python or Java 
 Smack demo apps as a starting point.
            • 
-        
          • Note that Google AppEngine does not support connections to CCS.
            • 
+        
          • Note that Google AppEngine does not support connections to XMPP (CCS).
            • 
         
          
       
          • 
     
        
   
 
 
-
        A full GCM implementation requires both a client implementation and a server
-implementation. For more
-information about implementing the client side, see 
-Implementing GCM Client.
        
 
 
        Choosing a GCM Connection Server
        
 
 
        Currently GCM provides two connection servers: 
-HTTP and CCS (XMPP). You can use them
-separately or in tandem. CCS messaging differs from GCM HTTP messaging in the following ways:
        
+HTTP and XMPP (CCS). You can use them
+separately or in tandem. XMPP (CCS) messaging differs from HTTP messaging in the following ways:
        
 
          
   
        • Upstream/Downstream messages
     
            
-      
          • GCM HTTP: Downstream only: cloud-to-device. 
            • 
-      
          • CCS: Upstream and downstream (device-to-cloud, cloud-to-device). 
            • 
+      
          • HTTP: Downstream only, cloud-to-device up to 4KB of data. 
            • 
+      
          • XMPP (CCS): Upstream and downstream (device-to-cloud, cloud-to-device),
+        up to 4 KB of data. 
            • 
     
          
   
          • 
-  
        • Asynchronous messaging
+  
        • Messaging (synchronous or asynchronous)
     
            
-      
          • GCM HTTP: 3rd-party app servers send messages as HTTP POST requests and
-wait for a response. This mechanism is synchronous and causes the sender to block
-before sending another message.
            • 
-      
          • CCS: 3rd-party app servers connect to Google infrastructure using a
-persistent XMPP connection and send/receive messages to/from all their devices
-at full line speed. CCS sends acknowledgment or failure notifications (in the
+      
          • HTTP: Synchronous. 3rd-party app servers send messages as HTTP POST requests and
+wait for a response. This mechanism is synchronous and blocks the sender from sending
+another message until the response is received.
            • 
+      
          • XMPP (CCS): Asynchronous. 3rd-party app servers send/receive messages to/from all their
+devices at full line speed over persistent XMPP connections.
+XMPP (CCS) sends acknowledgment or failure notifications (in the
 form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.
            • 
     
          
   
          • 
 
   
        • JSON
     
            
-      
          • GCM HTTP: JSON messages sent as HTTP POST.
            • 
-      
          • CCS: JSON messages encapsulated in XMPP messages.
            • 
+      
          • HTTP: JSON messages sent as HTTP POST.
            • 
+      
          • XMPP (CCS): JSON messages encapsulated in XMPP messages.
            • 
+    
          
+  
          • 
+  
        • Plain Text
+    
            
+      
          • HTTP: Plain Text messages sent as HTTP POST.
            • 
+      
          • XMPP (CCS): Not supported.
            • 
+    
          
+  
          • 
+  
        • Multicast downstream send to multiple registration IDs.
+    
            
+      
          • HTTP: Supported in JSON message format.
            • 
+      
          • XMPP (CCS): Not supported.
            • 
     
          
   
          • 
 
        
 
-
        Role of the 3rd-party Application Server
        
 
-
        Before you can write client Android applications that use the GCM feature, you must
-have an  application server that meets the following criteria:
        
+
        Sending Messages
        
 
-
          
-  
        • Able to communicate with your client.
          • 
-  
        • Able to  fire off properly formatted requests to the GCM server.
          • 
-  
        • Able to handle requests and resend them as needed, using
-exponential back-off.
          • 
-  
        • Able to store the API key and client registration IDs. The
-API key is included in the header of POST requests that send
-messages.
          • 
- 
        • Able to generate message IDs to uniquely identify each message it sends. Message IDs
-should be unique per sender ID.
          • 
-
        
+
        This section gives an overview of sending messages. For details of message syntax,
+see Server Reference.
        
 
-
        Sending Messages
        
+
        Overview
        
 
 
        Here is the general sequence of events that occurs when a 3rd-party application
-server sends a message:
        
+server sends a message (the details vary depending on the platform):
        
 
          
-  
        1. The application server sends a message to GCM servers.
          2. 
-  
        2. Google enqueues and stores the message in case the device is offline.
          3. 
-  
        3. When the device is online, Google sends the message to the device.
          4. 
-  
        4. On the device, the system broadcasts the message to the specified Android
-application via Intent broadcast with proper permissions, so that only the targeted
-Android application gets the message. This wakes the Android application up.
-The Android application does not need to be running beforehand to receive the message.
          5. 
-  
        5. The Android application processes the message. 
          6. 
+  
        6. The 3rd-party app server sends a message to GCM servers.
          7. 
+  
        7. The GCM connection server enqueues and stores the message if the device is offline.
          8. 
+  
        8. When the device is online, GCM connection server sends the message to the device.
          9. 
+  
        9. The client app processes the message. 
          10. 
 
        
 
-
        The following sections describe the basic requirements for
-sending messages.
        
+
        Implement send request
        
+
+
        The following sections describe the basic components involved in
+sending a request. See the Server Reference
+for details.
        
 
-
        Target
        
+
        Target
        
 
        Required. When your app server sends a message in GCM, it must specify a target.
        
-
        For HTTP you must specify the target as one of:
        
+
        For HTTP you must specify the target as one of the following:
        
 
          
 
        • registration_ids: For sending to 1 or more devices (up to 1000).
 When you send a message to multiple registration IDs, that is called a multicast message.
          • 
 
        • notification_key: For sending to multiple devices owned by a single user.
          • 
 
        
-
        For CCS (XMPP):
        
+
        For CCS (XMPP) you must specify the target as:
        
 
          
-
        • You must specify the target as the "to" field, where the "to"
+
        • {@code to}: This
 field may contain a single registration ID or a notification key.
-CCS does not support multicast messaging.
          • 
+XMPP (CCS) does not support multicast messaging.
 
        
-
        Payload
        
-
        Optional. If you are including a payload in the message, you use the data
-parameter to include the payload. This applies for both HTTP and CCS.
        
-
-
        Message parameters
        
-
-
        The following table lists the parameters that a 3rd-party app server might
-include in the JSON messages it sends to a connection server. See the "Where Supported"
-column for information about which connection servers support that particular
-parameter.
        
-
-
        
-  Table 1. Message Parameters JSON (CCS and HTTP).
        
-
-
-  
-    
-    
-
-
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-  
-  
-
-
- 
-    
-    
-
-
-  
-    
-    
-
-
-  
-    
-    
-
-
-  
-    
-    
-
-
-  
-    
-    
-
-
-
-  
-  
-
-
-
-  
-  
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
        ParameterDescriptionWhere Supported
        toIn CCS, this parameter is used in place of registration_ids to
-specify the recipient of a message. Its value must be a registration ID.
-The value is a string. Required.CCS
        message_idIn CCS, this parameter uniquely identifies a message in an XMPP connection.
-The value is a string that uniquely identifies the associated message. Required.CCS
        message_typeIn CCS, this parameter indicates a special status message, typically sent by the system.
-However, your app server also uses this parameter to send an 'ack' or 'nack'
-message back to the CCS connection server. For more discussion of this topic, see
-Cloud Connection Server. The value is a string. Optional.CCS
        registration_idsThis parameter specifies a string array containing 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). A request must include a recipient—this can be either a
-registration ID, an array of registration IDs, or a {@code notification_key}.
-Required.HTTP
        notification_keyThis parameter specifies a string that maps a single user to multiple
-registration IDs associated
-with that user. This allows a 3rd-party server to send a single message to
-multiple app instances (typically on multiple devices) owned by a single user.
-A 3rd-party server can use {@code notification_key} as the target for a message
-instead of an individual registration ID (or array of registration IDs). The maximum
-number of members allowed for a {@code notification_key} is 20. For more discussion
-of this topic, see User Notifications. Optional.
-HTTP. This feature is supported in CCS, but you use it by
-specifying a notification key in the "to" field.
        collapse_keyThis parameter specifies 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. Messages with collapse keys are also called
-send-to-sync messages.
-
        
-Note: 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 per device, each with a different collapse key.
-If you exceed
-this number GCM will only keep 4 collapse keys, with no guarantees about which
-ones they will be. See Advanced Topics for more
-discussion of this topic. Optional.        		CCS, HTTP
        dataThis parameter specifies a JSON object whose fields represents the
-key-value pairs of the message's
-payload data. If present, the payload data 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 (4kb). The values could be any JSON object, but we
-recommend using strings, since the values will be converted to strings in the GCM
-server anyway. If you want to include objects or other non-string data types
-(such as integers or booleans), you have to do the conversion to string yourself.
-Also note that the key cannot be a reserved word (from or any word
-starting with google.). Using words defined in this table as field
-names (such as collapse_key) could yield unpredictable outcomes and
-is not recommended. Optional.CCS, HTTP
        delay_while_idleThis parameter 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. The default value is false, and must be a JSON boolean. Optional.CCS, HTTP
        time_to_liveThis parameter specifies 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).CCS, HTTP
        restricted_package_nameThis parameter specifies a string containing the package
-name of your application. When set, messages
-are only sent to registration IDs that match the package name. Optional.
-  HTTP
        dry_runThis parameter allows developers to test a request without actually
-sending a message. Optional. The default value is false, and must
-be a JSON boolean.
-  HTTP
        delivery_receipt_requestedThis parameter lets you request confirmation of message delivery. When
-this parameter is set to true, CCS sends a
-delivery receipt when a device confirms that it received a message sent by CCS.
-The default value is false, and must be a JSON boolean. Optional.
        
-This parameter relates to 
-delivery receipts.
-        		CCS
        message_statusThis parameter specifies the status of the receipt message.
-The parameter appears inside the
-"data" field of a
-delivery receipt message. Currently the only possible value
-is MESSAGE_SENT_TO_DEVICE, which indicates that a device acknowledges
-receiving  a message sent by CCS.
        
-This parameter relates to 
-delivery receipts.        		CCS
        original_message_idThe value of this parameter is the ID of the original message that the server sent to
-the device. This parameter appears inside the "data" field of a
-delivery receipt message. 
        
-This parameter relates to 
-delivery receipts.        		CCS
        device_registration_idFor the purpose of tracking the delivery receipt, this parameter lists
-the registration ID of the device to which a given message was sent. This parameter
-appears inside the "data" field of a
-delivery receipt message. 
        
-This parameter relates to 
-delivery receipts.        		CCS
        
 
+
        Options
        
+
+
        There are various options the 3rd-party app server can set when sending a downstream
+message to a client app. See the 
+Server Reference for details. Here are a few examples of possible options:
        
+
+
          
+  
        • {@code collapse_key}: whether a message should be "send-to-sync" or a "message with
+payload".
          • 
+  
        • {@code time_to_live}: setting an expiration date for a message.
          • 
+  
        • {@code dry_run}: Test your server.
 
          If you want to test your request (either JSON or plain text) without delivering
-the message to the devices, you can set an optional HTTP or JSON parameter called
+the message to the devices, you can set an optional HTTP parameter called
 dry_run with the value true. The result will be almost
 identical to running the request without this parameter, except that the message
 will not be delivered to the devices. Consequently, the response will contain fake
 IDs for the message and multicast parameters.
          
+
          • 
+
        
 
-
        If you are using plain text instead of JSON, the message parameters must be set as
-HTTP parameters sent in the body, and their syntax is slightly different, as
-described in the following table:
-
-
        
-  Table 2. Message Parameters Plain Text (HTTP only).
        
-
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-
-    
-
-  
-  
-    
-    
-  
-  
-    
-    
-  
-
-  
-  
-
-
-  
-  
-
-
        ParameterDescription
        registration_idThis parameter specifies the registration ID of the single device
-receiving the message.
-Required.
        collapse_keySame as JSON (see previous table). Optional.
        data.<key>This parameter specifies 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. Also note that the key cannot
-be a reserved word (from or any word starting with
-google.). Using words defined in this table as field
-names (such as collapse_key) could yield unpredictable outcomes and
-is not recommended. Optional.
        delay_while_idleThis parameter specifies whether messages should be delivered when the device
-is asleep. A value of 1 or true indicates
-true, and anything else indicates false. Optional. The default
-value is false.
        time_to_liveSame as JSON (see previous table). Optional.
        restricted_package_nameSame as JSON (see previous table). Optional.
-  
        dry_runSame as JSON (see previous table). Optional.
-  
        
-
-
        Receiving Messages
        
-
-
        This is the sequence of events that occurs when an Android application
-installed on a mobile device receives a message:
        
+
        Payload
        
+
        Optional. If you are including a payload in the message, you use the data
+parameter to include the payload. This applies for both HTTP and XMPP.
        
+
+
        See the Server Reference for details on sending
+and receiving messages.
        
+
+
        Messaging Concepts and Best Practices
        
+
+
        This section has a discussion of general messaging topics.
        
+
+
        Send-to-Sync  vs. Messages with Payload
        
+
+
        Every message sent in GCM has the following characteristics:
        
+
          
+  
        • It has a payload limit of 4096 bytes.
          • 
+  
        • By default, it is stored by GCM for 4 weeks.
          • 
+
        
+
+
        But despite these similarities, messages can behave very differently depending
+on their particular settings. One major distinction between messages is whether
+they are collapsed (where each new message replaces the preceding message) or not
+collapsed (where each individual message is delivered). Every message sent in GCM
+is either a "send-to-sync" (collapsible) message or a "message with
+payload" (non-collapsible message).
        
+
+
        Send-to-sync messages
        
+
+
        A send-to-sync (collapsible) message is often 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. Another
+example would be a sports application that updates users with the latest score.
+Only the most recent message is relevant. 
        
+
+
        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 per device, each with a different collapse key.
+For example, Device A can have A1, A2, A3, and A4. Device B can have B1, B2, B3,
+and B4, and so on. If you exceed this number GCM will only keep 4 collapse keys, with no
+guarantees about which ones they will be.
        
+
+
        Messages with payload
        
+
+
        Unlike a send-to-sync message, every "message with payload"
+(non-collapsible message) is delivered. The payload the message contains can be
+up to 4kb. 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 application should respond by syncing with the server to recover the
+discarded messages. 
        
+
+
        Which should I use?
        
+  
        If your application does not need to use non-collapsible messages, collapsible
+messages are a better choice from a performance standpoint. However, if you use
+collapsible messages, remember that GCM only allows a maximum of 4 different collapse
+keys to be used by the GCM server per registration ID at any given time. You must
+not exceed this number, or it could cause unpredictable consequences.
        
+
+
        Setting an Expiration Date for a Message
        
+
        You can use the time_to_live parameter in the send request
+to specify the maximum lifespan of a message.
+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:
        
+
          
+  
        • Video chat incoming calls
          • 
+  
        • Expiring invitation events
          • 
+  
        • Calendar events
          • 
+
        
+
        Background 
        
+
        GCM usually delivers messages immediately after they are sent. However,
+this might not always be possible. For example, if the platform is Android,
+the device could be turned off, offline, or otherwise unavailable.
+Or 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
+},
+
        
+
+
+
        Receiving Messages from Multiple Senders
        
+
+
        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 number. 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.
        
+
+
        Note that there is limit of 100 multiple senders.
        
+
+
        Lifetime of a Message
        
+
+
        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.
+Collapsible messages are also called send-to-sync messages.
        
+
+
        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.
+

        
+Likewise, there is a limit on how many collapse_keys you can have for
+a particular device. GCM allows a maximum of 4 different collapse keys to be used
+by the GCM server per device
+any given time. In other words, the GCM server can simultaneously store 4 different
+send-to-sync messages, each with a different collapse key. If you exceed this number
+GCM will only keep 4 collapse keys, with no guarantees about which ones they will be.
+See Send-to-sync messages for more information.
+
        
+
+
        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.
        
+
+
        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 Cloud Console stats are broken down by messages sent to device, messages
+collapsed, and messages waiting for delivery.
        
+
+
        Throttling
        
+
        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.
        
 
-
          
-  
        1. The system receives the incoming message and extracts the raw key/value
-pairs from the message payload, if any.
          2. 
-  
        2. The system passes the key/value pairs to the targeted Android application
-in a com.google.android.c2dm.intent.RECEIVE Intent as a set of
-extras.
          3. 
-  
        3. The Android application extracts the raw data
-from the com.google.android.c2dm.intent.RECEIVE Intent
-by key and processes the data.
          4. 
-
        
 
-
        See the documentation for each connection server for more detail on how it
-handles responses.
        
diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs
index 0c48a0a..4e8e638 100644
--- a/docs/html/google/google_toc.cs
+++ b/docs/html/google/google_toc.cs
@@ -169,22 +169,15 @@
               HTTP
               
         
+        
      5. 
+            Server Reference
+        
        6. 
         
      6. 
               User Notifications
         
        7. 
-        
      7. 
-            Advanced Topics
-        
        8. 
         
      8. 
             Migration
         
        9. 
-        
       
   
 
-- 
cgit v1.1