765 lines
30 KiB
Plaintext
765 lines
30 KiB
Plaintext
page.title=Server Reference
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
|
|
<h2>In this document</h2>
|
|
|
|
<ol class="toc">
|
|
<li><a href="#downstream">Downstream Messages</a></li>
|
|
<ol class="toc">
|
|
<li><a href="#send-downstream">Sending a downstream message</a></li>
|
|
<li><a href="#interpret-downstream">Interpreting a downstream message response</a></li>
|
|
</ol>
|
|
<li><a href="#upstream">Upstream Messages (XMPP)</a>
|
|
<ol class="toc">
|
|
<li><a href="#interpret-upstream">Interpreting an upstream XMPP message</a></li>
|
|
<li><a href="#upstream-response">Sending an upstream XMPP message response</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#ccs">Cloud Connection Server Messages (XMPP)</a></li>
|
|
<li><a href="#error-codes">Downstream message error response codes (HTTP and XMPP)</a></li>
|
|
</ol>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<p>This document provides a reference for the syntax used to pass
|
|
messages back and forth in GCM. These messages fall into
|
|
the following broad categories:</p>
|
|
|
|
<ul>
|
|
<li><a href="#downstream">Downstream messages</a></li>
|
|
<li><a href="#upstream">Upstream messages</a></li>
|
|
<li><a href="#ccs">Cloud Connection Server messages (XMPP)</a></li>
|
|
<li><a href="#error-codes">Downstream message error response codes (HTTP and XMPP)</a></li>
|
|
</ul>
|
|
|
|
<p>The following sections describe the basic requirements for
|
|
sending messages.</p>
|
|
|
|
<h2 id="downstream">Downstream Messages</h2>
|
|
<p>This is the message that a 3rd-party app server sends to a client app.
|
|
</p>
|
|
<p>A downstream message includes the following components:</p>
|
|
<ul>
|
|
<li>Target: specifies the recipient of the message.</li>
|
|
<li>Options: specifies attributes of the message.</li>
|
|
<li>Payload: specifies additional content to be included in the message. Optional.</li>
|
|
</ul>
|
|
|
|
<p>The syntax for each of these components is described in the tables below. </p>
|
|
|
|
<h3 id="send-downstream">Sending a downstream message</h3>
|
|
|
|
<p>This section gives the syntax for sending a downstream messages. For JSON,
|
|
these messages can be either HTTP or XMPP. For plain text, these messages can only be HTTP.</p>
|
|
|
|
<h4>Downstream HTTP or XMPP messages (JSON)</h4>
|
|
|
|
<p>The following table lists the targets, options, and payload for HTTP or XMPP JSON messages.</p>
|
|
<p class="table-caption" id="table1">
|
|
<strong>Table 1.</strong> Targets, options, and payload for downstream HTTP or XMPP message (JSON).</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Protocol</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="4"><strong>Targets</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>to</code></td>
|
|
<td>XMPP</td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies the recipient of a message. </p>
|
|
<p>The value must be a registration ID or notification key.</p>
|
|
<p>This parameter is used in XMPP in place of {@code registration_ids} or {@code notification_key} in HTTP.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>registration_ids</code></td>
|
|
<td>HTTP</td>
|
|
<td>Required if {@code notification_key} not present, string array</td>
|
|
<td><p>This parameter specifies the list of devices (registration IDs)
|
|
receiving the message. It must contain at least 1 and at most 1000 registration IDs.</p>
|
|
<p>Multicast messages (sending to more than 1 registration IDs) are allowed using HTTP JSON format only.</p>
|
|
<p>This parameter or {@code notification_key} is used in HTTP in place of {@code to} in XMPP.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>notification_key</code></td>
|
|
<td>HTTP</td>
|
|
<td>Required if {@code registration_ids} not present, string</td>
|
|
<td><p>This parameter specifies the mapping of a single user to
|
|
multiple registration IDs associated with that user.</p>
|
|
<p>This allows a 3rd-party app server to send a single message to multiple app instances
|
|
(typically on multiple devices) owned by a single user.</p>
|
|
<p>A 3rd-party app 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 20.</p>
|
|
<p>This parameter or {@code registration_ids} is used in HTTP in place of {@code to} in XMPP.</p>
|
|
<p>See <a href="notifications.html">User Notifications</a> for details.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="4"><strong>Options</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_id</code></td>
|
|
<td>XMPP</td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter uniquely identifies a message in an XMPP connection.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>collapse_key</code></td>
|
|
<td>HTTP, XMPP</td>
|
|
<td>Optional, string</td>
|
|
<td><p>This parameters identifies a group of messages (e.g., with
|
|
{@code collapse_key: "Updates Available"}) that can be collapsed, so that only the
|
|
last message gets sent when delivery can be resumed. This is intended to avoid sending too
|
|
many of the same messages when the device comes back online or becomes active (see {@code delay_while_idle}).</p>
|
|
<p>Note that there is no guarantee of the order in which messages get sent.</p>
|
|
<p>Messages with collapse key are also called
|
|
<a href="{@docRoot}google/gcm/server.html#s2s">send-to-sync messages</a> messages.
|
|
</p>
|
|
<p>Note: A maximum of 4 different collapse keys is allowed at any given time. This means a
|
|
GCM connection server can simultaneously store 4 different send-to-sync messages per client app. If you
|
|
exceed this number, there is no guarantee which 4 collapse keys the GCM connection server will keep. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>delay_while_idle</code></td>
|
|
<td>HTTP, XMPP</td>
|
|
<td>Optional, JSON boolean</td>
|
|
<td>When this parameter is set to {@code true}, it indicates that the message should not be
|
|
sent until the device becomes active.</p>
|
|
<p>The default value is {@code false}.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>time_to_live</code></td>
|
|
<td>HTTP, XMPP</td>
|
|
<td>Optional, JSON number</td>
|
|
<td><p>This parameter specifies how long (in seconds) the message should be kept in GCM storage
|
|
if the device is offline. The maximum time to live supported is 4 weeks.</p>
|
|
<p>The default value is 4 weeks. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>delivery_receipt_
|
|
<br>requested</code></td>
|
|
<td>XMPP</td>
|
|
<td>Optional, JSON boolean</td>
|
|
<td><p>This parameter lets 3rd-party app server request confirmation of message delivery.</p>
|
|
<p>When this parameter is set to {@code true}, CCS sends a delivery receipt
|
|
when the device confirms that it received the message.</p>
|
|
<p>The default value is {@code false}.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>restricted_package_
|
|
<br>name</code></td>
|
|
<td>HTTP</td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies the package name of the application where the
|
|
registration IDs must match in order to receive the message.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>dry_run</code></td>
|
|
<td>HTTP</td>
|
|
<td>Optional, JSON boolean</td>
|
|
<td><p>This parameter, when set to {@code true}, allows developers to test a
|
|
request without actually sending a message.</p>
|
|
<p>The default value is {@code false}.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="4"><strong>Payload</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>data</code></td>
|
|
<td>HTTP, XMPP</td>
|
|
<td>Optional, JSON object</td>
|
|
<td><p>This parameter specifies the key-value pairs of the message's payload. There is
|
|
no limit on the number of key-value pairs, but there is a total message size limit of 4kb.</p>
|
|
<p>For instance, in Android, <code>data:{"score":"3x1"}</code> would result in an intent extra
|
|
named {@code score} with the string value {@code 3x1}.</p>
|
|
<p>The key should not be a reserved word ({@code from} or any word starting with
|
|
{@code google}). It is also not recommended to use words defined in this table
|
|
(such as {@code collapse_key}) because that could yield unpredictable outcomes. </p>
|
|
<p>Values in string types are recommended. You have to convert values in objects
|
|
or other non-string data types (e.g., integers or booleans) to string.</p></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Downstream HTTP messages (Plain Text)</h3>
|
|
|
|
<p>The following table lists the syntax for targets, options, and payload in plain
|
|
text downstream HTTP messages.</p>
|
|
|
|
<p class="table-caption" id="table2">
|
|
<strong>Table 2.</strong> Targets, options, and payload for downstream plain text HTTP messages.</p>
|
|
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Targets</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>registration _id</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies the client apps (registration ID) receiving the message.</p>
|
|
<p>Multicast messaging (sending to more than one registration ID) is allowed using HTTP JSON format only.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Options</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>collapse_key</code></td>
|
|
<td>Optional, string</td>
|
|
<td>See <a href="#table1">table 1</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>delay_while_idle</code></td>
|
|
<td>Optional, boolean or number</td>
|
|
<td>See <a href="#table1">table 1</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>time_to_live</code></td>
|
|
<td>Optional, number</td>
|
|
<td>See <a href="#table1">table 1</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>restricted_package_name</code></td>
|
|
<td>Optional, string</td>
|
|
<td>See <a href="#table1">table 1</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>dry_run </code></td>
|
|
<td>Optional, boolean</td>
|
|
<td>See <a href="#table1">table 1</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Payload</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>data.<key></code></td>
|
|
<td>Optional, string</td>
|
|
<td><p>This parameter specifies the key-value pairs of the message's payload.
|
|
There is no limit on the number of key-value parameters,
|
|
but there is a total message size limit of 4kb.</p>
|
|
<p>For instance, in Android, <code>data:{"score":"3x1"}</code> would result in an intent extra
|
|
named {@code score} with the string value {@code 3x1}.</p>
|
|
<p>The key should not be a reserved word ({@code from} or any word starting with
|
|
{@code google}). It is also not recommended to use words defined in this table
|
|
(such as {@code collapse_key}) because that could yield unpredictable outcomes.</p></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 id="interpret-downstream">Interpreting a Downstream Message Response</h3>
|
|
|
|
<p>This section describes the syntax of a response to a downstream message. A client
|
|
app or the GCM Connection Server sends the response to 3rd-party app server upon processing
|
|
the message request. </p>
|
|
|
|
<h4>Interpreting a downstream HTTP message response </h4>
|
|
<p>The 3rd-party app server should look at both the message response header and the body
|
|
to interpret the message response sent from the GCM Connection Server. The following table
|
|
describes the possible responses.</p>
|
|
<p>
|
|
|
|
<p class="table-caption" id="table3">
|
|
<strong>Table 3.</strong> Downstream HTTP message response header.</p>
|
|
<table border=1>
|
|
<tr>
|
|
<th>Response</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>200</td>
|
|
<td>Message was processed successfully. The response body will contain more
|
|
details about the message status, but its format will depend whether the request
|
|
was JSON or plain text. See <a href="#table4">table 4</a>
|
|
for more details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>400</td>
|
|
<td>Only applies for JSON requests.
|
|
Indicates that the request could not be parsed as JSON, or it contained invalid
|
|
fields (for instance, passing a string where a number was expected). The exact
|
|
failure reason is described in the response and the problem should be addressed
|
|
before the request can be retried.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>401</td>
|
|
<td>There was an error authenticating the sender account.
|
|
<a href="server.html#auth_error">Troubleshoot</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td>5xx</td>
|
|
<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
|
|
response. Application servers must implement exponential back-off.
|
|
<a href="server.html#internal_error">Troubleshoot</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The following table lists the fields in a downstream message response body
|
|
(JSON).</p>
|
|
|
|
|
|
<p class="table-caption" id="table4">
|
|
<strong>Table 4.</strong> Downstream HTTP message response body (JSON).</p>
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>multicast_id</code></td>
|
|
<td>Required, number</td>
|
|
<td>Unique ID (number) identifying the multicast message.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>success</code></td>
|
|
<td>Required, number</td>
|
|
<td>Number of messages that were processed without an error.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>failure</code></td>
|
|
<td>Required, number</td>
|
|
<td>Number of messages that could not be processed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>canonical_ids</code></td>
|
|
<td>Required, number</td>
|
|
<td>Number of results that contain a canonical registration ID. See the
|
|
<a href="{@docRoot}google/gcm/gcm.html#canonical">Overview</a> for more discussion of this topic.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>results</code></td>
|
|
<td>Optional, array object</td>
|
|
<td>Array of objects representing the status of the messages processed. The
|
|
objects are listed in the same order as the request (i.e., for each registration
|
|
ID in the request, its result is listed in the same index in the response).<br>
|
|
<ul>
|
|
<li><code>message_id</code>: String specifying a unique ID for each successfully processed
|
|
message.</li>
|
|
<li><code>registration_id</code>: Optional string specifying the canonical registration ID
|
|
for the client app that the message was processed and sent to. Sender should use this
|
|
value as the Registration ID for future requests. Otherwise, the messages might
|
|
be rejected.
|
|
</li>
|
|
<li><code>error</code>: String specifying the error that occurred when processing the
|
|
message for the recipient. The possible values can be found in <a href="#table11">table 11
|
|
</a>.</li>
|
|
</ul></td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<p class="table-caption" id="table5">
|
|
<strong>Table 5.</strong> Success response for downstream HTTP message response body (Plain Text).</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>id</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies the unique message ID that GCM server processed successfully.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>registration_id</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies the canonical registration ID for the client app that the message was
|
|
processed and sent to. Sender should replace the registration ID with this value on future requests,
|
|
otherwise, the messages might be rejected.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p class="table-caption" id="table6">
|
|
<strong>Table 6.</strong> Error response for downstream HTTP message response body (Plain Text).</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code Error}</td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies the error value while processing the message for the recipient.
|
|
See <a href="#table11">table 11</a> for details. </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Interpreting a downstream XMPP message response</h4>
|
|
|
|
<p>The following table lists the fields that appear in a downstream XMPP message response.</p>
|
|
|
|
<p class="table-caption" id="table7">
|
|
<strong>Table 7.</strong> Downstream message XMPP message response body.</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>from</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies who sent this response.</p>
|
|
<p>The value is the registration ID of the client app.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_id</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter uniquely identifies a message in an XMPP connection.
|
|
The value is a string that uniquely identifies the associated message.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_type</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies an 'ack' or 'nack' message from XMPP (CCS)
|
|
to the 3rd-party app server.</p>
|
|
<p>If the value is set to {@code nack}, the 3rd-party app server should look at
|
|
{@code error} and {@code error_description} to get failure information. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>error</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies an error related to the downstream message. It is set when the
|
|
{@code message_type} is {@code nack}. See <a href="#table11">table 6</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>error_description</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter provides descriptive information for the error. It is set
|
|
when the {@code message_type} is {@code nack}.</td>
|
|
</tr>
|
|
</table>
|
|
<h2 id="upstream">Upstream Messages (XMPP)</h2>
|
|
|
|
<p>An upstream message is a message the client app sends to the 3rd-party app server.
|
|
Currently only CCS (XMPP) supports upstream messaging.</p>
|
|
|
|
<h3 id="interpret-upstream">Interpreting an upstream XMPP message </h3>
|
|
<p>The following table describes the fields that appear in an upstream XMPP message.
|
|
|
|
<p class="table-caption" id="table8">
|
|
<strong>Table 8.</strong> Upstream XMPP messages.</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>from</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies who sent the message.</p>
|
|
<p>The value is the registration ID of the client app.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>category</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies the application package name of the client app that sent the message. </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_id</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies the unique ID of the message. </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>data</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies the key-value pairs of the message's payload.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 id="upstream-response">Sending an upstream XMPP message response</h3>
|
|
|
|
<p>The following table describes the response that 3rd-party app server is expected to send to
|
|
<a href="{@docRoot}google/gcm/ccs.html">XMPP (CCS)</a> in response to an
|
|
upstream message it (the app server) received.</p>
|
|
|
|
<p class="table-caption" id="table9">
|
|
<strong>Table 9.</strong> Upstream XMPP message response.</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>to</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies the recipient of a response message. </p>
|
|
<p>The value must be a registration ID of the client app that sent the upstream message.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_id</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies which message the response is intended for. The value must be
|
|
the {@code message_id} value from the corresponding upstream message.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_type</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies an {@code ack} message from a 3rd-party app server to CCS.</td>
|
|
</tr>
|
|
</table>
|
|
<h2 id="ccs">Cloud Connection Server Messages (XMPP) </h2>
|
|
<p>This is a message sent from XMPP (CCS) to a 3rd-party app server. Here are the primary types
|
|
of messages that XMPP (CCS) sends to the 3rd-party app server:</p>
|
|
<ul>
|
|
<li><strong>Delivery Receipt:</strong> If the 3rd-party app server included {@code delivery_receipt_requested}
|
|
in the downstream message, XMPP (CCS) sends a delivery receipt when it receives confirmation
|
|
that the device received the message.</li>
|
|
<li><strong>Control:</strong> These CCS-generated messages indicate that
|
|
action is required from the 3rd-party app server.</li>
|
|
</ul>
|
|
|
|
<p>The following table describes the fields included in the messages CCS
|
|
sends to a 3rd-party app server.</p>
|
|
|
|
<p class="table-caption" id="table10">
|
|
<strong>Table 10.</strong> GCM Cloud Connection Server messages (XMPP).</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Usage</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Common Field</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_type</code></td>
|
|
<td>Required, string</td>
|
|
<td><p>This parameter specifies the type of the CCS message: either delivery receipt or control.</p>
|
|
<p>When it is set to {@code receipt}, the message includes {@code from}, {@code message_id},
|
|
{@code category} and {@code data} fields to provide additional information.</p>
|
|
<p>When it is set to {@code control}, the message includes {@code control_type} to indicate the
|
|
type of control message.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Delivery receipt-specific</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>from</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter is set to {@code gcm.googleapis.com}, indicating that the
|
|
message is sent from CCS.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>message_id</code></td>
|
|
<td>Required, string</td>
|
|
<td>This parameter specifies the original message ID that the receipt is intended for,
|
|
prefixed with {@code dr2:} to indicate that the message is a delivery receipt. A 3rd-party app
|
|
server must send an {@code ack} message with this message ID to acknowledge that it
|
|
received this delivery receipt. See <a href="#table9">table 9</a> for the 'ack' message format.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>category</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies the application package name of the client app that
|
|
receives the message that this delivery receipt is reporting. This is available when
|
|
{@code message_type} is {@code receipt}.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>data</code></td>
|
|
<td>Optional, string</td>
|
|
<td>This parameter specifies the key-value pairs for the delivery receipt message. This is available
|
|
when the {@code message_type} is {@code receipt}.
|
|
<ul>
|
|
<li>{@code message_status}: This parameter specifies the status of the receipt message.
|
|
It is set to {@code MESSAGE_SENT_TO_DEVICE} to indicate the device has confirmed its receipt of
|
|
the original message.</li>
|
|
<li>{@code original_message_id}: This parameter specifies the ID of the original message
|
|
that the 3rd-party app server sent to the client app.</li>
|
|
<li>{@code device_registration_id}: This parameter specifies the registration ID of the
|
|
client app to which the original message was sent.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3"><strong>Control-specific</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>control_type</code></td>
|
|
<td>Optional, string</td>
|
|
<td><p>This parameter specifies the type of control message sent from CCS.</p>
|
|
<p>Currently, only {@code CONNECTION_DRAINING} is supported. XMPP (CCS) sends this control message
|
|
before it closes a connection to perform load balancing. As the connection drains, no more messages
|
|
are allowed to be sent to the connection, but existing messages in the pipeline will
|
|
continue to be processed.</p></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2 id="error-codes">Downstream message error response codes (HTTP and XMPP)</h2>
|
|
|
|
<p>The following table lists the error response codes for downstream messages (HTTP and XMPP).</p>
|
|
|
|
<p class="table-caption" id="table11">
|
|
<strong>Table 11.</strong> Downstream message error response codes.</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Error</th>
|
|
<th>HTTP Code</th>
|
|
<th>XMPP Code</th>
|
|
<th>Recommended Action</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Missing Registration ID</td>
|
|
<td>200 + error:MissingRegistration</td>
|
|
<td><code>INVALID_JSON</code></td>
|
|
<td>Check that the request contains a registration ID (either in the
|
|
{@code registration_id} in a plain text message, or in the {@code registration_ids} in JSON).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Invalid Registration ID</td>
|
|
<td>200 + error:InvalidRegistration</td>
|
|
<td><code>BAD_REGISTRATION</code></td>
|
|
<td>Check the format of the registration ID you pass to the server. Make sure it
|
|
matches the registration ID the client app receives from registering with GCM. Do not
|
|
truncate or add additional characters.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Unregistered Device</td>
|
|
<td>200 + error:NotRegistered</td>
|
|
<td><code>DEVICE_UNREGISTERED</code></td>
|
|
<td>An existing registration ID may cease to be valid in a number of scenarios, including:<br>
|
|
<ul>
|
|
<li>If the client app unregisters with GCM.</li>
|
|
<li>If the client app is automatically unregistered, which can happen if the user uninstalls the application.</li>
|
|
<li>If the registration ID expires (for example, Google might decide to refresh registration IDs).</li>
|
|
<li>If the client app is updated but the new version is not configured to receive messages.</li>
|
|
</ul>
|
|
For all these cases, remove this registration ID from the 3rd-party app
|
|
server and stop using it to send messages.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Invalid Package Name</td>
|
|
<td>200 + error:InvalidPackageName</td>
|
|
<td></td>
|
|
<td>Make sure the message was addressed to a registration ID whose package name
|
|
matches the value passed in the request.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Authentication Error</td>
|
|
<td>401</td>
|
|
<td> </td>
|
|
<td>The sender account used to send a message couldn't be authenticated. Possible causes are:<br>
|
|
<ul>
|
|
<li>Authorization header missing or with invalid syntax in HTTP request.</li>
|
|
<li>Invalid project number sent as key.</li>
|
|
<li>Key valid but with GCM service disabled.</li>
|
|
<li>Request originated from a server not whitelisted in the Server Key IPs.</li>
|
|
</ul>
|
|
Check that the token you're sending inside the Authentication header is
|
|
the correct API key associated with your project. See
|
|
<a href="{@docRoot}google/gcm/http.html#checkAPIkey">Checking the validity of an API Key
|
|
</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Mismatched Sender</td>
|
|
<td>200 + error:MismatchSenderId</td>
|
|
<td><code>BAD_REGISTRATION</code></td>
|
|
<td>A registration ID is tied to a certain group of senders. When a client app registers
|
|
for GCM, it must specify which senders are allowed to send messages. You should use one
|
|
of those sender IDs when sending messages to the client app. If you switch to a different
|
|
sender, the existing registration IDs won't work.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Invalid JSON</td>
|
|
<td>400</td>
|
|
<td><code>INVALID_JSON</code></td>
|
|
<td>Check that the JSON message is properly formatted and contains valid fields
|
|
(for instance, making sure the right data type is passed in).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Message Too Big</td>
|
|
<td>200 + error:MessageTooBig</td>
|
|
<td><code>INVALID_JSON</code></td>
|
|
<td>Check that the total size of the payload data included in a message does
|
|
not exceed 4096 bytes. This includes both the the keys and the values.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Invalid Data Key</td>
|
|
<td>200 + error:
|
|
<br />
|
|
InvalidDataKey</td>
|
|
<td><code>INVALID_JSON</code></td>
|
|
<td>Check that the payload data does not contain a key (such as {@code from} or any value
|
|
prefixed by {@code google}) that is used internally by GCM. Note that some words (such as {@code collapse_key})
|
|
are also used by GCM but are allowed in the payload, in which case the payload value
|
|
will be overridden by the GCM value.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Invalid Time to Live</td>
|
|
<td>200 + error:InvalidTtl</td>
|
|
<td><code>INVALID_JSON</code></td>
|
|
<td>Check that the value used in {@code time_to_live} is an integer representing a
|
|
duration in seconds between 0 and 2,419,200 (4 weeks).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Bad ACK message</td>
|
|
<td>N/A</td>
|
|
<td><code>BAD_ACK</code></td>
|
|
<td>Check that the 'ack' message is properly formatted before retrying. See
|
|
<a href="#table9">table 9</a> for details.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Timeout</td>
|
|
<td>5xx or 200 + error:Unavailable</td>
|
|
<td><code>SERVICE_UNAVAILABLE</code></td>
|
|
<td><p>The server couldn't process the request in time. Retry the same request, but you must:<br>
|
|
<ul>
|
|
<li>For HTTP: Honor the {@code Retry-After} header if it is included in the response from the
|
|
GCM Connection Server.</li>
|
|
<li>Implement exponential back-off in your retry mechanism. (e.g. if you waited one second
|
|
before the first retry, wait at least two second before the next one, then 4 seconds and so on).
|
|
If you're sending multiple messages, delay each one independently by an additional random amount
|
|
to avoid issuing a new request for all messages at the same time.</li>
|
|
<li>For CCS: The initial retry delay should be set to 1 second.</li>
|
|
</ul>
|
|
<p>Senders that cause problems risk being blacklisted.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Internal Server Error</td>
|
|
<td>500 or 200 + error:InternalServerError</td>
|
|
<td><code>INTERNAL_SERVER_
|
|
<br />
|
|
ERROR</code></td>
|
|
<td>The server encountered an error while trying to process the request. You could retry
|
|
the same request following the requirements listed in "Timeout" (see row above). If the error persists, please
|
|
report the problem in the {@code android-gcm group}.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Device Message Rate Exceeded</td>
|
|
<td>200 + error:
|
|
<br />DeviceMessageRate
|
|
<br />
|
|
Exceeded</td>
|
|
<td><code>DEVICE_MESSAGE_RATE<br />
|
|
_EXCEEDED</code></td>
|
|
<td>The rate of messages to a particular device is too high. Reduce the
|
|
number of messages sent to this device and do not immediately retry sending to this device.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Connection Draining</td>
|
|
<td>N/A</td>
|
|
<td><code>CONNECTION_DRAINING</code></td>
|
|
<td>The message couldn't be processed because the connection is draining. This happens because
|
|
periodically, XMPP (CCS) needs to close down a connection to perform load balancing. Retry the message over
|
|
another XMPP connection.</td>
|
|
</tr>
|
|
</table>
|