docs/html/google/gcm/server.jd

page.title=Implementing GCM Server
@jd:body

<div id="qv-wrapper">
<div id="qv">

<h2>In this document</h2>

<ol class="toc">
  <li><a href="#choose">Choosing a GCM Connection Server</a></li>
  <li><a href="#role">Role of the 3rd-party Application Server</a></li>
    <li><a href="#send-msg">Sending Messages</a>
    <ol class="toc">

      <li><a href="#target">Target</a></li>
      <li><a href="#payload">Payload</a></li>
      <li><a href="#params">Message parameters</a>
    </ol>
    </li>
  <li><a href="#receive">Receiving Messages</a> </li>
  </li>

</ol>

<h2>See Also</h2>

<ol class="toc">
<li><a href="gs.html">Getting Started</a></li>
<li><a href="client.html">Implementing GCM Client</a></li>
<li><a href="ccs.html">Cloud Connection Server (XMPP)</a></li>
<li><a href="http.html">HTTP Connection Server</a></li>


</ol>

</div>
</div>


<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
Android application (the &quot;client app&quot;) running on a device. For example,
Google provides connection servers for <a href="{@docRoot}google/gcm/http.html">
HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP).</li>
<li>A <strong>3rd-party application server</strong> that you must implement. This application
server sends data to a GCM-enabled Android application via the chosen GCM connection server.</li>
</ul>
</p>

<p>Here are the basic steps you follow to implement your 3rd-party app server:</p>

<ul>
      <li>Decide which GCM connection server(s) you want to use. Note that if you want to use
      upstream messaging from your client applications, you must use CCS. For a more detailed
      discussion of this, see <a href="#choose">
      Choosing a GCM Connection Server</a>.</li>
      <li>Decide how you want to implement your app server. For example:
        <ul>
          <li>If you decide to use the HTTP connection server, you can use the
GCM server helper library and demo app to help in implementing your app server.</li>
          <li>If you decide to use the XMPP connection server, you can use
the provided Python or Java <a href="http://www.igniterealtime.org/projects/smack/">
Smack</a> demo apps as a starting point.</li>
        <li>Note that Google AppEngine does not support connections to CCS.</li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

<p>A full GCM implementation requires both a client implementation and a server
implementation. For more
information about implementing the client side, see <a href="client.html">
Implementing GCM Client</a>.</p>

<h2 id="choose">Choosing a GCM Connection Server</h2>

<p>Currently GCM provides two connection servers: <a href="{@docRoot}google/gcm/http.html">
HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP). You can use them
separately or in tandem. CCS messaging differs from GCM HTTP messaging in the following ways:</p>
<ul>
  <li>Upstream/Downstream messages
    <ul>
      <li>GCM HTTP: Downstream only: cloud-to-device. </li>
      <li>CCS: Upstream and downstream (device-to-cloud, cloud-to-device). </li>
    </ul>
  </li>
  <li>Asynchronous messaging
    <ul>
      <li>GCM HTTP: 3rd-party app servers send messages as HTTP POST requests and
wait for a response. This mechanism is synchronous and causes the sender to block
before sending another message.</li>
      <li>CCS: 3rd-party app servers connect to Google infrastructure using a
persistent XMPP connection and send/receive messages to/from all their devices
at full line speed. CCS sends acknowledgment or failure notifications (in the
form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.</li>
    </ul>
  </li>

  <li>JSON
    <ul>
      <li>GCM HTTP: JSON messages sent as HTTP POST.</li>
      <li>CCS: JSON messages encapsulated in XMPP messages.</li>
    </ul>
  </li>
</ul>

<h2 id="role">Role of the 3rd-party Application Server</h2>

<p>Before you can write client Android applications that use the GCM feature, you must
have an  application server that meets the following criteria:</p>

<ul>
  <li>Able to communicate with your client.</li>
  <li>Able to  fire off properly formatted requests to the GCM server.</li>
  <li>Able to handle requests and resend them as needed, using
<a href="http://en.wikipedia.org/wiki/Exponential_backoff">exponential back-off.</a></li>
  <li>Able to store the API key and client registration IDs. The
API key is included in the header of POST requests that send
messages.</li>
 <li>Able to generate message IDs to uniquely identify each message it sends. Message IDs
should be unique per sender ID.</li>
</ul>

<h2 id="send-msg">Sending Messages</h2>

<p>Here is the general sequence of events that occurs when a 3rd-party application
server sends a message:</p>
<ol>
  <li>The application server sends a message to GCM servers.</li>
  <li>Google enqueues and stores the message in case the device is offline.</li>
  <li>When the device is online, Google sends the message to the device.</li>
  <li>On the device, the system broadcasts the message to the specified Android
application via Intent broadcast with proper permissions, so that only the targeted
Android application gets the message. This wakes the Android application up.
The Android application does not need to be running beforehand to receive the message.</li>
  <li>The Android application processes the message. </li>
</ol>

<p>The following sections describe the basic requirements for
sending messages.</p>

<h3 id="target">Target</h3>
<p>Required. When your app server sends a message in GCM, it must specify a target.</p>
<p>For HTTP you must specify the target as one of:</p>
<ul>
<li><code>registration_ids</code>: For sending to 1 or more devices (up to 1000).
When you send a message to multiple registration IDs, that is called a multicast message.</li>
<li><code>notification_key</code>: For sending to multiple devices owned by a single user.</li>
</ul>
<p>For CCS (XMPP):</p>
<ul>
<li>You must specify the target as the &quot;to&quot; field, where the &quot;to&quot;
field may contain a single registration ID or a notification key.
CCS does not support multicast messaging.</li>
</ul>
<h3 id="payload">Payload</h3>
<p>Optional. If you are including a payload in the message, you use the <code>data</code>
parameter to include the payload. This applies for both HTTP and CCS.</p>

<h3 id="params">Message parameters</h3>

<p>The following table lists the parameters that a 3rd-party app server might
include in the JSON messages it sends to a connection server. See the "Where Supported"
column for information about which connection servers support that particular
parameter.</p>

<p class="table-caption" id="table1">
  <strong>Table 1.</strong> Message Parameters JSON (CCS and HTTP).</p>

<table>
  <tr>
    <th>Parameter</th>
    <th>Description</th>
<th>Where Supported</th>
</tr>
  <td><code>to</code></td>
<td>In CCS, this parameter is used in place of <code>registration_ids</code> to
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, this parameter uniquely identifies a message in an XMPP connection.
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, 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>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
(see below). A request must include a recipient&mdash;this can be either a
registration ID, an array of registration IDs, or a {@code notification_key}.
Required.</td>
<td>HTTP</td>
</tr>
 <tr>
    <td><code>notification_key</code></td>
    <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 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
specifying a notification key in the &quot;to&quot; field.</td>
</tr>
  <tr>
    <td><code>collapse_key</code></td>
    <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. 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
used by the GCM server
at any given time. In other words, the GCM server can simultaneously store 4
different send-to-sync messages per device, each with a different collapse key.
If you exceed
this number GCM will only keep 4 collapse keys, with no guarantees about which
ones they will be. See <a href="adv.html#collapsible">Advanced Topics</a> for more
discussion of this topic. Optional.</td>
<td>CCS, HTTP</td>
</tr>
  <tr>
    <td><code>data</code></td>
    <td>This parameter specifies a JSON object whose fields represents the
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>.
There is no limit on the number of key/value pairs, though there is a limit on
the total size of the message (4kb). The values could be any JSON object, but we
recommend using strings, since the values will be converted to strings in the GCM
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>). Using words defined in this table as field
names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
is not recommended. Optional.</td>
<td>CCS, HTTP</td>
</tr>
  <tr>
    <td><code>delay_while_idle</code></td>
    <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>
<td>CCS, HTTP</td>
</tr>
  <tr>
    <td><code>time_to_live</code></td>
    <td>This parameter specifies how long (in seconds) the message should be kept on GCM
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>This parameter specifies a string containing the package
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>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
the message to the devices, you can set an optional HTTP or JSON parameter called
<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 parameters.</p>

<p>If you are using plain text instead of JSON, the message parameters must be set as
HTTP parameters sent in the body, and their syntax is slightly different, as
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>Parameter</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>registration_id</code></td>
    <td>This parameter specifies the registration ID of the single device
receiving the message.
Required.</td>
  </tr>
  <tr>
    <td><code>collapse_key</code></td>
    <td>Same as JSON (see previous table). Optional.</td>
  </tr>
  <tr>
    <td><code>data.&lt;key&gt;</code></td>

    <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>). Using words defined in this table as field
names (such as <code>collapse_key</code>) could yield unpredictable outcomes and
is not recommended. Optional.</td>

  </tr>
  <tr>
    <td><code>delay_while_idle</code></td>
    <td>This parameter specifies whether messages should be delivered when the device
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>
    <td><code>time_to_live</code></td>
    <td>Same as JSON (see previous table). Optional.</td>
  </tr>
<tr>
  <td><code>restricted_package_name</code></td>
  <td>Same as JSON (see previous table). Optional.
  </td>
</tr>
<tr>
  <td><code>dry_run</code></td>
  <td>Same as JSON (see previous table). Optional.
  </td>
</tr>
</table>

<h2 id="receive">Receiving Messages</h2>

<p>This is the sequence of events that occurs when an Android application
installed on a mobile device receives a message:</p>

<ol>
  <li>The system receives the incoming message and extracts the raw key/value
pairs from the message payload, if any.</li>
  <li>The system passes the key/value pairs to the targeted Android application
in a <code>com.google.android.c2dm.intent.RECEIVE</code> Intent as a set of
extras.</li>
  <li>The Android application extracts the raw data
from the <code>com.google.android.c2dm.intent.RECEIVE</code><code> </code>Intent
by key and processes the data.</li>
</ol>

<p>See the documentation for each connection server for more detail on how it
handles responses.</p>