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

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

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

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

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

<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

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

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

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>

&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

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

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

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

<ul>

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

  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>

  <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 &quot;data&quot;} 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 &quot;statistics&quot; link next to the app for which you

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

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

This could be a lightweight message telling the Android application

</div>

</div>

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

implementation.

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

(GCM) implementation.

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

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

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

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

GCM APIs</a>.</p>

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

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