am 2aa70413: am 76b66a9a: am 2b4d89b7: am eca07bfa: Merge "Doc change: Update...

<h2>In this document</h2>

<h2>In this document</h2>

<ol class="toc">

<ol class="toc">

  <li><a href="#usage">How to Use CCS</a>

  <li><a href="#connecting">Establishing a Connection</a>

    <ol class="toc">

    <ol class="toc">

      <li><a href="#auth">Authentication</a></li>

      <li><a href="#auth">Authentication</a></li>

      </ol>

      </ol>

<p class="note"><strong>Note:</strong> To try out this feature, sign up using

<p class="note"><strong>Note:</strong> To try out this feature, sign up using

<a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p>

<a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p>

<p>The GCM Cloud Connection Server (CCS) is a connection server based on XMPP.

<p>The GCM Cloud Connection Server (CCS) is an XMPP endpoint that provides a

CCS allows 3rd-party app servers (which you're

persistent, asynchronous, bidirectional connection to Google servers. The

responsible for implementing) to communicate

connection can be used to send and receive messages between your server and

with Android devices by  establishing a persistent TCP connection with Google

your users' GCM-connected devices.</p>

servers using the XMPP protocol. This communication is asynchronous and bidirectional.</p>

<p>You can continue to use the HTTP request mechanism to send messages to GCM

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

servers, side-by-side with CCS which uses XMPP. Some of the benefits of CCS include:</p>

<ul>

<ul>

  <li>The asynchronous nature of XMPP allows you to send more messages with fewer

  <li>The asynchronous nature of XMPP allows you to send more messages with fewer

resources.</li>

resources.</li>

  <li>Communication is bidirectional&mdash;not only can the server send messages

  <li>Communication is bidirectional&mdash;not only can your server send messages

to the device, but the device can send messages back to the server.</li>

to the device, but the device can send messages back to your server.</li>

<li>You can send messages back using the same connection used for receiving,

  <li>The device can send messages back using the same connection used for receiving,

thereby improving battery life.</li>

thereby improving battery life.</li>

</ul>

</ul>

<a href="server.html#params">Implementing GCM Server</a> for a list of all the message

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

parameters and which connection server(s) supports them.</p>

<h2 id="connecting">Establishing a Connection</h2>

<h2 id="usage">How to Use CCS</h2>

<p>CCS just uses XMPP as an authenticated transport layer, so you can use most

XMPP libraries to manage the connection. For an example, see <a href="#smack">

Java sample using the Smack library</a>.</p>

<p>GCM Cloud Connection Server (CCS) is an XMPP endpoint, running on

<p>The CCS XMPP endpoint runs at {@code gcm.googleapis.com:5235}. When testing

{@code http://gcm.googleapis.com} port 5235.</p>

functionality (with non-production users), you should instead connect to

{@code gcm-staging.googleapis.com:5236} (note the different port). Testing on

staging (a smaller environment where the latest CCS builds run) is beneficial

both for isolating real users from test code, as well as for early detection of

unexpected behavior changes.</p>

<p>CCS requires a Transport Layer Security (TLS) connection. That means the  XMPP

<p>The connection has two important requirements:</p>

client must initiate a TLS connection.

For example in Java, you would call {@code setSocketFactory(SSLSocketFactory)}.</p>

<p>CCS requires a SASL PLAIN authentication mechanism using

<ul>

{@code <your_GCM_Sender_Id>@gcm.googleapis.com} (GCM sender ID) and the

  <li>You must initiate a Transport Layer Security (TLS) connection. Note that

API key as the password, where the sender ID and API key are the same as described

  CCS doesn't currently support the <a href="http://xmpp.org/rfcs/rfc3920.html"

in <a href="gs.html">Getting Started</a>.</p>

  class="external-link" target="_android">STARTTLS extension</a>.</li>

  <li>CCS requires a SASL PLAIN authentication mechanism using

  {@code <your_GCM_Sender_Id>@gcm.googleapis.com} (GCM sender ID)

  and the API key as the password, where the sender ID and API key are the same

  as described in <a href="gs.html">Getting Started</a>.</li>

</ul>

<p> You can use most XMPP libraries to interact with CCS.</p>

<p>If at any point the connection fails, you should immediately reconnect.

There is no need to back off after a disconnect that happens after

authentication.</p>

<h3 id="auth">Authentication</h3>

<h3 id="auth">Authentication</h3>

</pre>

</pre>

<h4>Server</h4>

<h4>Server</h4>

<pre>&lt;str:features xmlns:str=&quot;http://etherx.jabber.org/streams&quot;&gt;

<pre>&lt;str:features xmlns:str=&quot;http://etherx.jabber.org/streams&quot;&gt;

 <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">

 <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">

   <mechanism>X-OAUTH2</mechanism>

   <mechanism>X-OAUTH2</mechanism>

   <mechanism>X-GOOGLE-TOKEN</mechanism>

   <mechanism>X-GOOGLE-TOKEN</mechanism>

   <mechanism>PLAIN</mechanism>

   <mechanism>PLAIN</mechanism>

 </mechanisms>

 </mechanisms>

</str:features>

</str:features>

</pre>

</pre>

<pre>&lt;success xmlns=&quot;urn:ietf:params:xml:ns:xmpp-sasl&quot;/&gt;</pre>

<pre>&lt;success xmlns=&quot;urn:ietf:params:xml:ns:xmpp-sasl&quot;/&gt;</pre>

<h2 id="format">Message Format</h2>

<h2 id="format">Message Format</h2>

<p>CCS uses normal XMPP <code>&lt;message&gt;</code> stanzas. The body of the message must be:

<p>Once the XMPP connection is established, CCS and your server use normal XMPP

</p>

<code>&lt;message&gt;</code> stanzas to send JSON-encoded messages back and

forth. The body of the <code>&lt;message&gt;</code> must be:</p>

<pre>

<pre>

<gcm xmlns:google:mobile:data>

<gcm xmlns:google:mobile:data>

    <em>JSON payload</em>

    <em>JSON payload</em>

</gcm>

</gcm>

</pre>

</pre>

<p>The JSON payload for server-to-device is similar to what the GCM http endpoint

<p>The JSON payload for regular GCM messages is similar to

uses, with these exceptions:</p>

<a href="http.html#request">what the GCM http endpoint uses</a>, with these

exceptions:</p>

<ul>

<ul>

  <li>There is no support for multiple recipients.</li>

  <li>There is no support for multiple recipients.</li>

  <li>{@code to} is used instead of {@code registration_ids}.</li>

  <li>{@code to} is used instead of {@code registration_ids}.</li>

{@code message_id} to identify a message sent from 3rd-party app servers to CCS.

{@code message_id} to identify a message sent from 3rd-party app servers to CCS.

Therefore, it's important that this {@code message_id} not only be unique, but

Therefore, it's important that this {@code message_id} not only be unique, but

always present.</li>

always present.</li>

</ul>

<li>For ACK/NACK messages that are special control messages, you also need to

<p>In addition to regular GCM messages, control messages are sent, indicated by

include a {@code message_type} field in the JSON message. The value can be either

the {@code message_type} field in the JSON object. The value can be either

'ack' or 'nack'. For example:

'ack' or 'nack', or 'control' (see formats below). Any GCM message with an

unknown {@code message_type} can be ignored by your server.</p>

<pre>message_type = ('ack');</pre>

  </li>

</ul>

<p>For each device message your app server receives from CCS, it needs to send

<p>For each device message your app server receives from CCS, it needs to send

an ACK message.

an ACK message.

It never needs to send a NACK message. If you don't send an ACK for a message,

It never needs to send a NACK message. If you don't send an ACK for a message,

&lt;/message&gt;</pre>

&lt;/message&gt;</pre>

<p>The following table lists some of the more common NACK error codes.</p>

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

<p class="table-caption" id="table1">

<p class="table-caption" id="table1">

  <strong>Table 1.</strong> NACK error codes.</p>

  <strong>Table 1.</strong> NACK error codes.</p>

<th>Description</th>

<th>Description</th>

</tr>

</tr>

<tr>

<tr>

<td>{@code BAD_ACK}</td>

<td>The ACK message is improperly formed.</td>

</tr>

<tr>

<td>{@code BAD_REGISTRATION}</td>

<td>{@code BAD_REGISTRATION}</td>

<td>The device has a registration ID, but it's invalid.</td>

<td>The device has a registration ID, but it's invalid or expired.</td>

</tr>

<tr>

<td>{@code CONNECTION_DRAINING}</td>

<td>The message couldn't be processed because the connection is draining. The

message should be immediately retried over another connection.</td>

</tr>

</tr>

<tr>

<tr>

<td>{@code DEVICE_UNREGISTERED}</td>

<td>{@code DEVICE_UNREGISTERED}</td>

<td>The server encountered an error while trying to process the request.</td>

<td>The server encountered an error while trying to process the request.</td>

</tr>

</tr>

<tr>

<tr>

<td>{@code SERVICE_UNAVAILABLE}</td>

<td>{@code INVALID_JSON}</td>

<td>The CCS connection server is temporarily unavailable, try again later

<td>The JSON message payload was not valid.</td>

(using exponential backoff, etc.).</td>

</tr>

</tr>

<tr>

<tr>

<td>{@code BAD_ACK}</td>

<td>{@code QUOTA_EXCEEDED}</td>

<td>The ACK message is improperly formed.</td>

<td>The rate of messages to a particular registration ID (in other words, to a

</tr>

sender/device pair) is too high. If you want to retry the message, try using a slower

<tr>

rate.</td>

<td>{@code AUTHENTICATION_FAILED}</td>

<td>This is a 401 error indicating that there was an error authenticating the sender account.</td>

</tr>

<tr>

<td>{@code INVALID_TTL}</td>

<td>There was an error in the supplied "time to live" value.</td>

</tr>

</tr>

<tr>

<tr>

<td>{@code JSON_TYPE_ERROR}</td>

<td>{@code SERVICE_UNAVAILABLE}</td>

<td>There was an error in the supplied JSON data type.</td>

<td>CCS is not currently able to process the message. The

message should be retried over the same connection using exponential backoff

with an initial delay of 1 second.</td>

</tr>

</tr>

</table>

</table>

</message>

</message>

</pre>

</pre>

<h4 id="control">Control messages</h4>

<p>Periodically, CCS needs to close down a connection to perform load balancing. Before it

closes the connection, CCS sends a {@code CONNECTION_DRAINING} message to indicate that the connection is being drained

and will be closed soon. "Draining" refers to shutting off the flow of messages coming into a

connection, but allowing whatever is already in the pipeline to continue. When you receive

a {@code CONNECTION_DRAINING} message, you should immediately begin sending messages to another CCS

connection, opening a new connection if necessary. You should, however, keep the original

connection open and continue receiving messages that may come over the connection (and

ACKing them)&mdash;CCS will handle initiating a connection close when it is ready.</p>

<p>The {@code CONNECTION_DRAINING} message looks like this:</p>

<pre>&lt;message&gt;

  <data:gcm xmlns:data="google:mobile:data">

  {

    "message_type":"control"

    "control_type":"CONNECTION_DRAINING"

  }

  </data:gcm>

&lt;/message&gt;</pre>

<p>{@code CONNECTION_DRAINING} is currently the only {@code control_type} supported.</p>

<h2 id="upstream">Upstream Messages</h2>

<h2 id="upstream">Upstream Messages</h2>

<p>Every message sent to CCS receives either an ACK or a NACK response. Messages

<p>Every message sent to CCS receives either an ACK or a NACK response. Messages

that haven't received one of these responses are considered pending. If the pending

that haven't received one of these responses are considered pending. If the pending

message count reaches 1000, the 3rd-party app server should stop sending new messages

message count reaches 100, the 3rd-party app server should stop sending new messages

and wait for CCS to acknowledge some of the existing pending messages as illustrated in

and wait for CCS to acknowledge some of the existing pending messages as illustrated in

figure 1:</p>

figure 1:</p>

if there are too many unacknowledged messages. Therefore, the 3rd-party app server

if there are too many unacknowledged messages. Therefore, the 3rd-party app server

should "ACK" upstream messages, received from the client application via CCS, as soon as possible

should "ACK" upstream messages, received from the client application via CCS, as soon as possible

to maintain a constant flow of incoming messages. The aforementioned pending message limit doesn't

to maintain a constant flow of incoming messages. The aforementioned pending message limit doesn't

apply to these ACKs. Even if the pending message count reaches 1000, the 3rd-party app server

apply to these ACKs. Even if the pending message count reaches 100, the 3rd-party app server

should continue sending ACKs for messages received from CCS to avoid blocking delivery of new

should continue sending ACKs for messages received from CCS to avoid blocking delivery of new

upstream messages.</p>

upstream messages.</p>

PASSWORD = "API Key"

PASSWORD = "API Key"

REGISTRATION_ID = "Registration Id of the target device"

REGISTRATION_ID = "Registration Id of the target device"

unacked_messages_quota = 1000

unacked_messages_quota = 100

send_queue = []

send_queue = []

# Return a random alphanumerical id

# Return a random alphanumerical id