am 63ee1976: am 2b20b9d2: am 3e92c4a2: am 1867f2cf: Merge "Doc update: deliv receipt, rate exceeded, bug fixes." into klp-modular-docs

* commit '63ee197682bf7cf831950087028b2a81902f92c9':
  Doc update: deliv receipt, rate exceeded, bug fixes.

docs/html/google/gcm/adv.jd

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

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

@@ -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
+<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,
 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
 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">
+<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,
 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

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

@@ -25,12 +25,12 @@ page.tags=cloud,push,messaging
 </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
 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>
 <p>To create a Google API project:</p>

docs/html/google/gcm/http.jd

@@ -33,13 +33,16 @@ page.title=GCM HTTP Connection Server
 </div>
 </div>
 
-<p>This document describes the GCM HTTP connection server. Connection servers
+<p>This document describes the Google Cloud Messaging (GCM) HTTP
+connection server. Connection servers
 are the Google-provided servers that take messages from the 3rd-party
 application server and sending them to the device.</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>
 
-
+<p>See
-<p class="note"><strong>Note:</strong> See
 <a href="server.html#params">Implementing GCM Server</a> for a list of all the message
 parameters and which connection server(s) supports them.</p>
 
@@ -163,7 +166,7 @@ before the request can be retried.</td>
   </tr>
   <tr>
     <td>5xx</td>
-    <td>Errors in the 500-599 range (such as 500 or 503) indicate that there wa
+    <td>Errors 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 <code>Retry-After</code> header included in the
@@ -416,6 +419,12 @@ A message was addressed to a registration ID whose package name did not match
 the value passed in the request. Happens when error code is
 <code>InvalidPackageName</code>.
 </dd>
+
+<dt id="big_msg"><strong>Device Message Rate Exceeded</strong></dt>
+  <dd>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 retry sending to this device immediately.
+<br/>Happens when error code is <code>DeviceMessageRateExceeded</code>.</dd>
+
 </dl>
 
 <h3 id="example-responses">Example responses</h3>

docs/html/google/gcm/index.jd

@@ -13,11 +13,11 @@ header.hide=1
 
   <h1 itemprop="name" style="margin-bottom:0;">Google Cloud Messaging for Android</h1>
   <p itemprop="description">
-  Google Cloud Messaging for Android (GCM) is a service that allows you to send data
+  Google Cloud Messaging (GCM) for Android is a service that allows you to send data
 from your server to your users' Android-powered device, and also to receive messages from
 devices on the same connection. The GCM service handles all aspects of queueing of messages
-and delivery to the target Android application running on the target device. GCM is
+and delivery to the target Android application running on the target device, and it is
-completely free no matter how big your messaging needs are, and there are no quotas.
+completely free.
 </p>
 
 </div>

docs/html/google/gcm/notifications.jd

@@ -83,7 +83,7 @@ message body is JSON.</p>
 <h2 id="gen-server">Generate a Notification Key on the Server</h2>
 
 <p>To generate a notification key on the server, you create a new
-create a new <code>notification_key</code> and map it to a
+<code>notification_key</code> and map it to a
 <code>notification_key_name</code>.</p>
 
 <p>This example shows how to create a new <code>notification_key</code> for a
@@ -268,7 +268,7 @@ notification key operations.</p>
 
 <p>When you make a request to create a {@code notification_key} or to add/remove its
 regIDs, a successful response always returns the <code>notification_key</code>.
-his is the {@code notification_key} you will use for sending messages:</p>
+Use the returned {@code notification_key} for sending messages:</p>
 
 <pre>HTTP status: 200
 { 

docs/html/google/gcm/server.jd

@@ -37,7 +37,7 @@ page.title=Implementing GCM Server
 </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
@@ -168,36 +168,37 @@ column for information about which connection servers support that particular
 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
+<td>In CCS, this parameter is used in place of <code>registration_ids</code> to
-recipient of a message. Its value must be a registration ID.
+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
+<td>In CCS, this parameter uniquely identifies a message in an XMPP connection.
-string that uniquely identifies the associated message. The value is a string. Required.</td>
+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
@@ -208,12 +209,13 @@ Required.</td>
 </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
@@ -221,13 +223,14 @@ specifying a notification key in the &quot;to&quot; field.</td>
 </tr>
   <tr>
     <td><code>collapse_key</code></td>
-    <td>An arbitrary string (such as &quot;Updates Available&quot;) that is used
+    <td>This parameter specifies an arbitrary string (such as
+&quot;Updates Available&quot;) 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 &quot;last&quot; 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
@@ -242,8 +245,9 @@ discussion of this topic. Optional.</td>
 </tr>
   <tr>
     <td><code>data</code></td>
-    <td>A JSON object whose fields represents the key-value pairs of the message's
+    <td>This parameter specifies a JSON object whose fields represents the
-payload data. If present, the payload data it will be
+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>.
@@ -253,17 +257,14 @@ recommend using strings, since the values will be converted to strings in the GC
 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
+starting with <code>google.</code>). Using words defined in this table as field
-some reserved words (such as <code>collapse_key</code>) that are technically
+names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
-allowed in payload data. However, if the request also contains the word, the
+is not recommended. Optional.</td>
-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>
 <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>
@@ -271,26 +272,70 @@ sent. The default value is <code>false</code>, and must be a JSON boolean. Optio
 </tr>
   <tr>
     <td><code>time_to_live</code></td>
-    <td>How long (in seconds) the message should be kept on GCM storage if the
+    <td>This parameter specifies how long (in seconds) the message should be kept on GCM
-device is offline. Optional (default time-to-live is 4 weeks, and must be set as
+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
+  <td>This parameter specifies a string containing the package
-will only be sent to registration IDs that match the package name. Optional.
+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>&quot;data&quot;</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>&quot;data&quot;</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>&quot;data&quot;</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
@@ -298,21 +343,23 @@ the message to the devices, you can set an optional HTTP or JSON parameter calle
 <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>
+IDs for the message and multicast parameters.</p>
 
-<h3 id="plain-text">Plain text (HTTP only)</h3>
+<p>If you are using plain text instead of JSON, the message parameters must be set as
-
-<p>If you are using plain text instead of JSON, the message fields 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>
@@ -322,24 +369,23 @@ Required.</td>
   <tr>
     <td><code>data.&lt;key&gt;</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
+<code>google.</code>). Using words defined in this table as field
-(such as <code>collapse_key</code>) that are technically allowed in payload data.
+names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
-However, if the request also contains the word, the value in the request will
+is not recommended. Optional.</td>
-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>
 
   </tr>
   <tr>
     <td><code>delay_while_idle</code></td>
-    <td>Should be represented as <code>1</code> or <code>true</code> for
+    <td>This parameter specifies whether messages should be delivered when the device
-<code>true</code>, anything else for <code>false</code>. Optional. The default
+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>