Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 13d7ea46 authored by kmccormick's avatar kmccormick Committed by Joe Fernandez
Browse files

DO NOT MERGE - Doc update: deliv receipt, rate exceeded, bug fixes. 

Cherry-pick from: Change-Id: I17d9604da9a894501c7701174e4f7c61dfa9e80e

Fix for:
b/17936796

Change-Id: I17d9604da9a894501c7701174e4f7c61dfa9e80e
parent 0fa6edce

docs/html/google/gcm/adv.jd

+2 −1
Original line number Diff line number Diff line
@@ -261,7 +261,7 @@ is either a "send-to-sync" (collapsible) message or a "message wi 
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
@@ -288,6 +288,7 @@ and B4, and so on. If you exceed this number GCM will only keep 4 collapse keys, 
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

docs/html/google/gcm/ccs.jd

+25 −33
Original line number Diff line number Diff line
@@ -21,7 +21,7 @@ page.title=GCM Cloud Connection Server (XMPP) 
      </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>
@@ -45,11 +45,15 @@ page.title=GCM Cloud Connection Server (XMPP) 
</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>
@@ -259,22 +263,6 @@ message is &quot;nack&quot;. A NACK message contains:</p> 
&lt;/message&gt;

</pre>



<p>Quota exceeded:</p>



<pre>&lt;message&gt;

 &lt;gcm xmlns=&quot;google:mobile:data&quot;&gt;

 {

   &quot;message_type&quot;:&quot;nack&quot;,

   &quot;message_id&quot;:&quot;msgId1&quot;,

   &quot;from&quot;:&quot;APA91bHFOtaQGSwupt5l1og&quot;,

   &quot;error&quot;:&quot;QUOTA_EXCEEDED&quot;,

   &quot;error_description&quot;:&quot;Short-term downstream quota exceeded for this registration id&quot;

 }

 &lt;/gcm&gt;

&lt;/message&gt;

</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>
@@ -312,11 +300,11 @@ message should be immediately retried over another connection.</td> 
<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>
@@ -429,15 +417,17 @@ response to the above message:</p> 
  &lt;/gcm&gt;

&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;
@@ -457,8 +447,10 @@ message with <code>&quot;delivery_receipt_requested&quot;</code> set to <code>tr 
&lt;/message&gt;

</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;
@@ -483,12 +475,12 @@ app server:</p> 
<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>

docs/html/google/gcm/client.jd

+11 −11
Original line number Diff line number Diff line
@@ -34,14 +34,14 @@ page.tags=cloud,push,messaging 
</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
@@ -57,8 +57,8 @@ registration ID), and a broadcast receiver to receive messages sent by GCM. 
<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>
@@ -159,7 +159,7 @@ could not run properly. </li> 
<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
@@ -456,7 +456,7 @@ private void storeRegistrationId(Context context, String regId) { 
<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>
@@ -652,7 +652,7 @@ your sender ID and API key. 


<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

docs/html/google/gcm/gcm.jd

+1 −1
Original line number Diff line number Diff line
@@ -21,7 +21,7 @@ page.title=Overview 
</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

docs/html/google/gcm/gs.jd

+4 −4
Original line number Diff line number Diff line
@@ -25,12 +25,12 @@ page.tags=cloud,push,messaging 
</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>