</li>
<li><a href="#upstream">Upstream Messages</a>
<ol>
- <li><a href="#receipts">Receive return receipts</a></li>
+ <li><a href="#receipts">Receive delivery receipts</a></li>
</ol>
</li>
<li><a href="#flow">Flow Control</a> </li>
</div>
</div>
-<p>The GCM Cloud Connection Server (CCS) is an XMPP endpoint that provides a
+<p>The Google Cloud Messaging (GCM) Cloud Connection Server (CCS) is an XMPP endpoint that provides a
persistent, asynchronous, bidirectional connection to Google servers. The
connection can be used to send and receive messages between your server and
your users' GCM-connected devices.</p>
+<p class="note"><strong>Note:</strong> The content in this document
+applies to <a href="http://developer.chrome.com/apps/cloudMessaging">
+GCM with Chrome apps</a> as well as Android.
+
<p>You can continue to use the HTTP request mechanism to send messages to GCM
servers, side-by-side with CCS which uses XMPP. Some of the benefits of CCS include:</p>
</message>
</pre>
-<p>Quota exceeded:</p>
-
-<pre><message>
- <gcm xmlns="google:mobile:data">
- {
- "message_type":"nack",
- "message_id":"msgId1",
- "from":"APA91bHFOtaQGSwupt5l1og",
- "error":"QUOTA_EXCEEDED",
- "error_description":"Short-term downstream quota exceeded for this registration id"
- }
- </gcm>
-</message>
-</pre>
-
-
<p>The following table lists 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}.</p>
<td>{@code INVALID_JSON}</td>
<td>The JSON message payload is not valid.</td>
</tr>
-<tr>
-<td>{@code QUOTA_EXCEEDED}</td>
-<td>The rate of messages to a particular registration ID (in other words, to a
-sender/device pair) is too high. If you want to retry the message, try using a slower
-rate.</td>
+<td>{@code DEVICE_MESSAGE_RATE_EXCEEDED}</td>
+<td>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 replaces {@code QUOTA_EXCEEDED},
+which has been deprecated.</td>
</tr>
<tr>
<td>{@code SERVICE_UNAVAILABLE}</td>
</gcm>
</message></pre>
-<h3 id="receipts">Receive return receipts</h3>
+<h3 id="receipts">Receive delivery receipts</h3>
-<p>You can use upstream messaging to get receipt notifications, confirming
-that a given message was sent to a device. Your 3rd-party app server receives the receipt
-notification from CCS once the message has been sent to the device.</p>
+<p>You can use upstream messaging to get delivery receipts (sent from CCS to
+your 3rd party app server) when
+a device confirms that it received a message sent by CCS.</p>
<p>To enable this feature, the message your 3rd-party app server sends to CCS must include
a field called <code>"delivery_receipt_requested"</code>. When this field is set to
-<code>true</code>, CCS sends a return receipt. Here is an XMPP stanza containing a JSON
+<code>true</code>, CCS sends a delivery receipt when a device confirms that it received a particular message.</p>
+
+<p>Here is an XMPP stanza containing a JSON
message with <code>"delivery_receipt_requested"</code> set to <code>true</code>:</p>
<pre><message id="">
</message>
</pre>
-<p>Here is an example of a receipt notification message that CCS sends back to your 3rd-party
-app server:</p>
+
+
+<p>Here is an example of the delivery receipt that CCS sends to tell your 3rd-party
+app server that a device received a message that CCS sent it:</p>
</p>
<pre><message id="">
<ul>
<li>The {@code "message_type"} is set to {@code "receipt"}.
<li>The {@code "message_status"} is set to {@code "MESSAGE_SENT_TO_DEVICE"},
- indicating that the message was delivered. Notice that in this case,
+ indicating that the device received the message. Notice that in this case,
{@code "message_status"} is not a field but rather part of the data payload.</li>
<li>The receipt message ID consists of the original message ID, but with a
-<code>dr:</code> prefix. Your 3rd-party app server must send an ACK back with this ID,
+<code>dr2:</code> prefix. Your 3rd-party app server must send an ACK back with this ID,
which in this example is {@code dr2:m-1366082849205}.</li>
- <li>The original message ID and status are inside the
+ <li>The original message ID, the device registration ID, and the status are inside the
{@code "data"} field.</li>
</ul>
</div>
</div>
-<p>A GCM client is a GCM-enabled app that runs on an Android device. To write your
-client code, we recommend that you use the
-<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">
-{@code GoogleCloudMessaging}</a> APIs.
+<p>A Google Cloud Messaging (GCM) client is a GCM-enabled app that runs on an
+Android device. To write your client code, we recommend that you use the
+<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">
+GCM APIs</a>.
The client helper library that was offered in previous versions of GCM still works,
but it has been superseded by the more efficient
-<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">
-{@code GoogleCloudMessaging}</a> APIs.</p>
+<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">
+GCM APIs</a>.</p>
<p>A full GCM implementation requires both a client implementation and a server
implementation. For more
<h2 id="play-services">Step 1: Set Up Google Play Services</h2>
<p>To write your client application, use the
-<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">
-{@code GoogleCloudMessaging}</a> API.
+<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">
+GCM APIs</a>.
To use this API, you must set up your project to use the Google Play services SDK,
as described in <a href="/google/play-services/setup.html">Setup Google Play
Services SDK</a>.</p>
<p>Finally, write your application. This section features a sample client
application that illustrates how to use the
<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">
-{@code GoogleCloudMessaging}</a> APIs. The sample consists of a main activity
+{@code GoogleCloudMessaging}</a> API. The sample consists of a main activity
({@code DemoActivity}), a {@link android.support.v4.content.WakefulBroadcastReceiver}
({@code GcmBroadcastReceiver}), and an {@link android.app.IntentService}
({@code GcmIntentService}). You can find the complete source code for this sample at the
<p>When the user clicks the app's <strong>Send</strong> button, the app sends an
upstream message using the
<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">
-{@code GoogleCloudMessaging}</a> APIs. In order to receive the upstream message,
+{@code GoogleCloudMessaging}</a> API. In order to receive the upstream message,
your server should be connected to CCS. You can use one of the demo servers in
<a href="ccs.html#implement">Implementing an XMPP-based App Server</a> to run the sample and connect
to CCS.</p>
<p>To view statistics and any error messages for your GCM applications:</p>
<ol>
- <li> Go to the <code><a href="http://play.google.com/apps/publish">Developer Console</a></code>.</li>
+ <li> Go to the <a href="http://play.google.com/apps/publish">Developer Console</a>.</li>
<li>Login with your developer account.
<p>You will see a page that has a list of all of your apps.</p></li>
<li> Click on the "statistics" link next to the app for which you
</div>
-<p>The server side of GCM consists of 2 components:</p>
+<p>The server side of Google Cloud Messaging (GCM) consists of 2 components:</p>
<ul>
<li>Google-provided <strong>GCM Connection Servers</strong>
take messages from a 3rd-party application server and send them to a GCM-enabled
parameter.</p>
<p class="table-caption" id="table1">
- <strong>Table 1.</strong> Message parameters.</p>
+ <strong>Table 1.</strong> Message Parameters JSON (CCS and HTTP).</p>
<table>
<tr>
- <th>Field</th>
+ <th>Parameter</th>
<th>Description</th>
<th>Where Supported</th>
</tr>
<td><code>to</code></td>
-<td>In CCS, used in place of <code>registration_ids</code> to specify the
-recipient of a message. Its value must be a registration ID.
+<td>In CCS, this parameter is used in place of <code>registration_ids</code> to
+specify the recipient of a message. Its value must be a registration ID.
The value is a string. Required.</td>
<td>CCS</td>
</tr>
<tr>
<td><code>message_id</code></td>
-<td>In CCS, uniquely identifies a message in an XMPP connection. The value is a
-string that uniquely identifies the associated message. The value is a string. Required.</td>
+<td>In CCS, this parameter uniquely identifies a message in an XMPP connection.
+The value is a string that uniquely identifies the associated message. Required.</td>
<td>CCS</td>
</tr>
<tr>
<td><code>message_type</code></td>
-<td>In CCS, indicates a special status message, typically sent by the system.
+<td>In 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
<a href="ccs.html">Cloud Connection Server</a>. The value is a string. Optional.</td>
<td>CCS</td>
<tr>
<td><code>registration_ids</code></td>
- <td>A string array with the list of devices (registration IDs) receiving the
+ <td>This 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
</tr>
<tr>
<td><code>notification_key</code></td>
- <td>A string that maps a single user to multiple registration IDs associated
+ <td>This 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 10. For more discussion
+number of members allowed for a {@code notification_key} is 20. For more discussion
of this topic, see <a href="notifications.html">User Notifications</a>. Optional.
</td>
<td style="width:100px">HTTP. This feature is supported in CCS, but you use it by
</tr>
<tr>
<td><code>collapse_key</code></td>
- <td>An arbitrary string (such as "Updates Available") that is used
+ <td>This 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. Collapse keys are also called
+message sent by the application server. Messages with collapse keys are also called
<a href="#s2s">send-to-sync messages</a>.
<br>
<strong>Note:</strong> GCM allows a maximum of 4 different collapse keys to be
</tr>
<tr>
<td><code>data</code></td>
- <td>A JSON object whose fields represents the key-value pairs of the message's
-payload data. If present, the payload data it will be
+ <td>This 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, <code>"data":{"score":"3x1"}</code> would result in an intent extra
named <code>score</code> whose value is the string <code>3x1</code>.
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 (<code>from</code> or any word
-starting with <code>google.</code>). To complicate things slightly, there are
-some reserved words (such as <code>collapse_key</code>) that are technically
-allowed in payload data. However, if the request also contains the word, the
-value in the request will overwrite the value in the payload data. Hence using
-words that are defined as field names in this table is not recommended, even in
-cases where they are technically allowed. Optional.</td>
+starting with <code>google.</code>). Using words defined in this table as field
+names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
+is not recommended. Optional.</td>
<td>CCS, HTTP</td>
</tr>
<tr>
<td><code>delay_while_idle</code></td>
- <td>If included, indicates that the message should not be sent immediately
+ <td>This 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 <code>collapse_key</code> value will be
sent. The default value is <code>false</code>, and must be a JSON boolean. Optional.</td>
</tr>
<tr>
<td><code>time_to_live</code></td>
- <td>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
+ <td>This 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).</td>
<td>CCS, HTTP</td>
</tr>
<tr>
<td><code>restricted_package_name</code></td>
- <td>A string containing the package name of your application. When set, messages
-will only be sent to registration IDs that match the package name. Optional.
+ <td>This 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.
</td>
<td>HTTP</td>
</tr>
<tr>
<td><code>dry_run</code></td>
- <td>If included, allows developers to test their request without actually
+ <td>This parameter allows developers to test a request without actually
sending a message. Optional. The default value is <code>false</code>, and must
be a JSON boolean.
</td>
<td>HTTP</td>
</tr>
+<tr>
+ <td><code>delivery_receipt_requested</code></td>
+ <td>This parameter lets you request confirmation of message delivery. When
+this parameter is set to <code>true</code>, CCS sends a
+delivery receipt when a device confirms that it received a message sent by CCS.
+The default value is <code>false</code>, and must be a JSON boolean. Optional.<br />
+This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}>
+delivery receipts</a>.
+</td>
+ <td>CCS</td>
+</tr>
+<tr>
+ <td><code>message_status</code></td>
+ <td>This parameter specifies the status of the receipt message.
+The parameter appears inside the
+<code>"data"</code> field of a
+delivery receipt message. Currently the only possible value
+is <code>MESSAGE_SENT_TO_DEVICE</code>, which indicates that a device acknowledges
+receiving a message sent by CCS.<br />
+This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}>
+delivery receipts</a>.</td>
+ <td>CCS</td>
+</tr>
+<tr>
+ <td><code>original_message_id</code></td>
+ <td>The value of this parameter is the ID of the original message that the server sent to
+the device. This parameter appears inside the <code>"data"</code> field of a
+delivery receipt message. <br />
+This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}>
+delivery receipts</a>.</td>
+ <td>CCS</td>
+</tr>
+<tr>
+ <td><code>device_registration_id</code></td>
+ <td>For 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 <code>"data"</code> field of a
+delivery receipt message. <br />
+This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}>
+delivery receipts</a>.</td>
+ <td>CCS</td>
+</tr>
+
</table>
<p>If you want to test your request (either JSON or plain text) without delivering
<code>dry_run</code> with the value <code>true</code>. 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 fields.</p>
-
-<h3 id="plain-text">Plain text (HTTP only)</h3>
+IDs for the message and multicast parameters.</p>
-<p>If you are using plain text instead of JSON, the message fields must be set as
+<p>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 below:
+described in the following table:
+
+<p class="table-caption" id="table2">
+ <strong>Table 2.</strong> Message Parameters Plain Text (HTTP only).</p>
<table>
<tr>
- <th>Field</th>
+ <th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td><code>registration_id</code></td>
- <td>Must contain the registration ID of the single device receiving the message.
+ <td>This parameter specifies the registration ID of the single device
+receiving the message.
Required.</td>
</tr>
<tr>
<tr>
<td><code>data.<key></code></td>
- <td>Payload data, expressed as parameters prefixed with <code>data.</code> and
+ <td>This parameter specifies payload data, expressed as parameters
+prefixed with <code>data.</code> and
suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would
result in an intent extra named <code>score</code> whose value is the string
<code>3x1</code>. 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 (<code>from</code> or any word starting with
-<code>google.</code>). To complicate things slightly, there are some reserved words
-(such as <code>collapse_key</code>) that are technically allowed in payload data.
-However, if the request also contains the word, the value in the request will
-overwrite the value in the payload data. Hence using words that are defined as
-field names in this table is not recommended, even in cases where they are
-technically allowed. Optional.</td>
+<code>google.</code>). Using words defined in this table as field
+names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
+is not recommended. Optional.</td>
</tr>
<tr>
<td><code>delay_while_idle</code></td>
- <td>Should be represented as <code>1</code> or <code>true</code> for
-<code>true</code>, anything else for <code>false</code>. Optional. The default
+ <td>This parameter specifies whether messages should be delivered when the device
+is asleep. A value of <code>1</code> or <code>true</code> indicates
+<code>true</code>, and anything else indicates <code>false</code>. Optional. The default
value is <code>false</code>.</td>
</tr>
<tr>
OSDN Git Service
