am 1867f2cf: Merge "Doc update: deliv receipt, rate exceeded, bug fixes." into klp-modular-docs

payload" (non-collapsible message). These concepts are described in more

payload" (non-collapsible message). These concepts are described in more

detail in the following sections.</p>

detail in the following sections.</p>

<h3 id="s2s"><strong>Send-to-sync messages</strong></h3>

<h3 id="s2s">Send-to-sync messages</h3>

<p>A send-to-sync (collapsible) message is often a &quot;tickle&quot; that tells

<p>A send-to-sync (collapsible) message is often a &quot;tickle&quot; that tells

a mobile application to sync data from the server. For example, suppose you have

a mobile application to sync data from the server. For example, suppose you have

guarantees about which ones they will be.</p>

guarantees about which ones they will be.</p>

<h3 id="payload">Messages with payload</h3>

<h3 id="payload">Messages with payload</h3>

<p>Unlike a send-to-sync message, every &quot;message with payload&quot;

<p>Unlike a send-to-sync message, every &quot;message with payload&quot;

(non-collapsible message) is delivered. The payload the message contains can be

(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

up to 4kb. For example, here is a JSON-formatted message in an IM application in

      </li>

      </li>

  <li><a href="#upstream">Upstream Messages</a>

  <li><a href="#upstream">Upstream Messages</a>

    <ol>

    <ol>

      <li><a href="#receipts">Receive return receipts</a></li>

      <li><a href="#receipts">Receive delivery receipts</a></li>

    </ol>

    </ol>

  </li>

  </li>

  <li><a href="#flow">Flow Control</a> </li>

  <li><a href="#flow">Flow Control</a> </li>

</div>

</div>

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

persistent, asynchronous, bidirectional connection to Google servers. The

connection can be used to send and receive messages between your server and

connection can be used to send and receive messages between your server and

your users' GCM-connected devices.</p>

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

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

servers, side-by-side with CCS which uses XMPP. Some of the benefits of CCS include:</p>

</message>

</message>

</pre>

</pre>

<p>Quota exceeded:</p>

<pre>&lt;message&gt;

 <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

<p>The following table lists NACK error codes. Unless otherwise

indicated, a NACKed message should not be retried. Unexpected NACK error codes

indicated, a NACKed message should not be retried. Unexpected NACK error codes

should be treated the same as {@code INTERNAL_SERVER_ERROR}.</p>

should be treated the same as {@code INTERNAL_SERVER_ERROR}.</p>

<td>{@code INVALID_JSON}</td>

<td>{@code INVALID_JSON}</td>

<td>The JSON message payload is not valid.</td>

<td>The JSON message payload is not valid.</td>

</tr>

</tr>

<tr>

<td>{@code DEVICE_MESSAGE_RATE_EXCEEDED}</td>

<td>{@code QUOTA_EXCEEDED}</td>

<td>The rate of messages to a particular device is too high. You should reduce

<td>The rate of messages to a particular registration ID (in other words, to a

the number of messages sent to this device and should not immediately retry

sender/device pair) is too high. If you want to retry the message, try using a slower

sending to this device. This error code replaces {@code QUOTA_EXCEEDED},

rate.</td>

which has been deprecated.</td>

</tr>

</tr>

<tr>

<tr>

  <td>{@code SERVICE_UNAVAILABLE}</td>

  <td>{@code SERVICE_UNAVAILABLE}</td>

  </gcm>

  </gcm>

&lt;/message&gt;</pre>

&lt;/message&gt;</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

<p>You can use upstream messaging to get delivery receipts (sent from CCS to

that a given message was sent to a device. Your 3rd-party app server receives the receipt

your 3rd party app server) when

notification from CCS once the message has been sent to the device.</p>

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

<p>To enable this feature, the message your 3rd-party app server sends to CCS must include

a field called <code>&quot;delivery_receipt_requested&quot;</code>. When this field is set to

a field called <code>&quot;delivery_receipt_requested&quot;</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>&quot;delivery_receipt_requested&quot;</code> set to <code>true</code>:</p>

message with <code>&quot;delivery_receipt_requested&quot;</code> set to <code>true</code>:</p>

<pre>&lt;message id=&quot;&quot;&gt;

<pre>&lt;message id=&quot;&quot;&gt;

</message>

</message>

</pre>

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

</p>

<pre>&lt;message id=&quot;&quot;&gt;

<pre>&lt;message id=&quot;&quot;&gt;

<ul>

<ul>

  <li>The {@code &quot;message_type&quot;} is set to {@code &quot;receipt&quot;}.

  <li>The {@code &quot;message_type&quot;} is set to {@code &quot;receipt&quot;}.

  <li>The {@code &quot;message_status&quot;} is set to {@code &quot;MESSAGE_SENT_TO_DEVICE&quot;},

  <li>The {@code &quot;message_status&quot;} is set to {@code &quot;MESSAGE_SENT_TO_DEVICE&quot;},

  indicating that the message was delivered. Notice that in this case,

  indicating that the device received the message. Notice that in this case,

{@code &quot;message_status&quot;} is not a field but rather part of the data payload.</li>

{@code &quot;message_status&quot;} 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

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

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 &quot;data&quot;} field.</li>

{@code &quot;data&quot;} field.</li>

</ul>

</ul>

</div>

</div>

</div>

</div>

<p>A GCM client is a GCM-enabled app that runs on an Android device. To write your

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

client code, we recommend that you use the

Android device. To write your client code, we recommend that you use the

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">

{@code GoogleCloudMessaging}</a> APIs.

GCM APIs</a>.

The client helper library that was offered in previous versions of GCM still works,

The client helper library that was offered in previous versions of GCM still works,

but it has been superseded by the more efficient

but it has been superseded by the more efficient

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">

{@code GoogleCloudMessaging}</a> APIs.</p>

GCM APIs</a>.</p>

<p>A full GCM implementation requires both a client implementation and a server

<p>A full GCM implementation requires both a client implementation and a server

implementation. For more

implementation. For more

<h2 id="play-services">Step 1: Set Up Google Play Services</h2>

<h2 id="play-services">Step 1: Set Up Google Play Services</h2>

<p>To write your client application, use the

<p>To write your client application, use the

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">

{@code GoogleCloudMessaging}</a> API.

GCM APIs</a>.

To use this API, you must set up your project to use the Google Play services SDK,

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

as described in <a href="/google/play-services/setup.html">Setup Google Play

Services SDK</a>.</p>

Services SDK</a>.</p>

<p>Finally, write your application. This section features a sample client

<p>Finally, write your application. This section features a sample client

application that illustrates how to use the

application that illustrates how to use the

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<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 DemoActivity}), a {@link android.support.v4.content.WakefulBroadcastReceiver}

({@code GcmBroadcastReceiver}), and an {@link android.app.IntentService}

({@code GcmBroadcastReceiver}), and an {@link android.app.IntentService}

({@code GcmIntentService}). You can find the complete source code for this sample at the

({@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

<p>When the user clicks the app's <strong>Send</strong> button, the app sends an

upstream message using the

upstream message using the

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<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

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

<a href="ccs.html#implement">Implementing an XMPP-based App Server</a> to run the sample and connect

to CCS.</p>

to CCS.</p>

<p>To view  statistics and any error messages for your GCM applications:</p>

<p>To view  statistics and any error messages for your GCM applications:</p>

<ol>

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

  <li>Login with your developer account.

  <p>You will see a page that has a list of all of your apps.</p></li>

  <p>You will see a page that has a list of all of your apps.</p></li>

  <li> Click on the &quot;statistics&quot; link next to the app for which you

  <li> Click on the &quot;statistics&quot; link next to the app for which you

</div>

</div>

</div>

</div>

<p>Google Cloud Messaging for Android (GCM) is a free service that helps

<p>Google Cloud Messaging (GCM) for Android is a free service that helps

developers  send data from servers to their Android applications on  Android

developers  send data from servers to their Android applications on  Android

devices, and upstream messages from the user's device back to the cloud.

devices, and upstream messages from the user's device back to the cloud.

This could be a lightweight message telling the Android application

This could be a lightweight message telling the Android application

</div>

</div>

</div>

</div>

<p>This document tells you how to get started setting up a GCM

<p>This document tells you how to get started setting up a Google Cloud Messaging

implementation.

(GCM) implementation.

Before you begin, make sure to <a href="/google/play-services/setup.html">set up

Before you begin, make sure to <a href="/google/play-services/setup.html">set up

the Google Play Services SDK</a>. You need this SDK to use the

the Google Play Services SDK</a>. You need this SDK to use the

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html">

{@code GoogleCloudMessaging}</a> methods.</p>

GCM APIs</a>.</p>

<h2 id="create-proj">Creating a Google API project</h2>

<h2 id="create-proj">Creating a Google API project</h2>

<p>To create a Google API project:</p>

<p>To create a Google API project:</p>