1 page.title=GCM Cloud Connection Server 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>Quickview</h2> 8 9 <ul> 10 <li>Get an introduction to key CCS terms and concepts.</li> 11 <li>Learn how to send and receive both upstream and downstream messages in CCS.</li> 12 </ul> 13 14 15 <h2>In this document</h2> 16 17 <ol class="toc"> 18 <li><a href="#gcm">CCS vs. GCM HTTP</a> </li> 19 <li><a href="#usage">How to Use CCS</a> 20 <ol> 21 <li><a href="#send_msg">Sending Messages</a></li> 22 <li><a href="#format">Message Format</a></li> 23 <li><a href="#msg_examples">Message Examples</a></li> 24 </ol> 25 </li> 26 <li><a href="#flow">Flow Control</a> </li> 27 </ol> 28 29 <h2>See Also</h2> 30 31 <ol class="toc"> 32 <li><a href="{@docRoot}google/play-services/gcm/gs.html">Getting Started</a></li> 33 <li><a href="https://services.google.com/fb/forms/gcm/" class="external-link" target="_android">CCS and User Notifications Signup Form</a></li> 34 </ol> 35 36 </div> 37 </div> 38 39 <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> 40 41 <p>The GCM Cloud Connection Server (CCS) allows third party servers to communicate with Android devices by establishing a persistent TCP connection with Google servers using the XMPP protocol. This communication is asynchronous and bidirectional.</p> 42 <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> 43 <ul> 44 <li>The asynchronous nature of XMPP allows you to send more messages with fewer resources.</li> 45 <li>Communication is bidirectional—not only can the server send messages to the device, but the device can send messages back to the server.</li> 46 <li>You can send messages back using the same connection used for receiving, thereby improving battery life.</li> 47 </ul> 48 49 <p>The upstream messaging (device-to-cloud) feature of CCS is part of the Google Play services platform. Upstream messaging is available through the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">{@code GoogleCloudMessaging}</a> APIs. To use upstream messaging and the new streamlined registration process, you must <a href="{@docRoot}google/play-services/setup.html">set up</a> the Google Play services SDK.</p> 50 51 <p class="note"><strong>Note:</strong> For an example of an XMPP server, see <a href="server.html#xmpp">GCM Server</a>. 52 53 <h2 id="gcm">CCS vs. GCM HTTP</h2> 54 55 <p>CCS messaging differs from GCM HTTP messaging in the following ways:</p> 56 <ul> 57 <li>Upstream/Downstream messages 58 <ul> 59 <li>GCM HTTP: Downstream only: cloud-to-device. </li> 60 <li>CCS: Upstream and downstream (device-to-cloud, cloud-to-device). </li> 61 </ul> 62 </li> 63 <li>Asynchronous messaging 64 <ul> 65 <li>GCM HTTP: 3rd-party 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> 66 <li>CCS: 3rd-party 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 acknowledgements or failure notifications (in the form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.</li> 67 </ul> 68 </li> 69 70 <li>JSON 71 <ul> 72 <li>GCM HTTP: JSON messages sent as HTTP POST.</li> 73 <li>CCS: JSON messages encapsulated in XMPP messages.</li> 74 </ul> 75 </li> 76 </ul> 77 <p>This document describes how to use CCS. For general concepts and information on how to use GCM HTTP, see the <a href="gcm.html">GCM Architectural Overview</a>.</p> 78 79 <h2 id="usage">How to Use CCS</h2> 80 81 <p>GCM Cloud Connection Server (CCS) is an XMPP endpoint, running on {@code http://gcm.googleapis.com} port 5235.</p> 82 83 <p>CCS requires a Transport Layer Security (TLS) connection. That means the XMPP client must initiate a TLS connection. 84 For example in smack, you would call {@code setSocketFactory(SSLSocketFactory)}, similar to old style SSL XMPP connections and https.</p> 85 86 <p>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>.</p> 87 88 <p> You can use most XMPP libraries to interact with CCS.</p> 89 90 <h3 id="send_msg">Sending messages</h3> 91 92 <p>The following snippets illustrate how to perform authentication in CCS.</p> 93 <h4>Client</h4> 94 <pre><stream:stream to="gcm.googleapis.com" 95 version="1.0" xmlns="jabber:client" 96 xmlns:stream="http://etherx.jabber.org/streams"/>; 97 </pre> 98 <h4>Server</h4> 99 <pre><str:features xmlns:str="http://etherx.jabber.org/streams">; 100 <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> 101 <mechanism>X-OAUTH2</mechanism> 102 <mechanism>X-GOOGLE-TOKEN</mechanism> 103 <mechanism>PLAIN</mechanism> 104 </mechanisms> 105 </str:features> 106 </pre> 107 108 <h4>Client</h4> 109 <pre><auth mechanism="PLAIN" 110 xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb 111 mRyb2lkLmNvbQAxMjYyMDAzNDc5FzNAcHJvamVjdHMtZ2EtLmFuZHJvaWQuY29tAEFJe 112 mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth> 113 </pre> 114 <h4>Server</h4> 115 <pre><success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/></pre> 116 117 <h3 id="format">Message Format</h3> 118 <p>CCS uses normal XMPP <code><message></code> stanzas. The body of the message must be: 119 </p> 120 <pre> 121 <gcm xmlns:google:mobile:data> 122 <em>JSON payload</em> 123 </gcm> 124 </pre> 125 126 <p>The JSON payload for server-to-device is similar to what the GCM http endpoint uses, with these exceptions:</p> 127 <ul> 128 <li>There is no support for multiple recipients.</li> 129 <li>{@code to} is used instead of {@code registration_ids}.</li> 130 <li>CCS adds the field {@code message_id}, which is required. This ID uniquely identifies the message in an XMPP connection. The ACK or NACK from CCS uses the {@code message_id} to identify a message sent from 3rd-party servers to CCS. Therefore, it's important that this {@code message_id} not only be unique, but always present.</li> 131 132 <li>For ACK/NACK messages that are special control messages, you also need to include a {@code message_type} field in the JSON message. For example: 133 134 <pre>message_type = ('ack' OR 'nack');</pre> 135 </li> 136 </ul> 137 <p>For each message a device sends to the server, you need to send an ACK message. You never need to send a NACK message. If you don't send an ACK for a message, CCS will just resend it. 138 </p> 139 <p>CCS also sends an ACK or NACK for each server-to-device message. If you do not receive either, it means that the TCP connection was closed in the middle of the operation and your server needs to resend the messages. 140 </p> 141 142 <h3 id="msg_examples">Message Examples</h3> 143 144 <p>Here is an XMPP stanza containing the JSON message from a 3rd-party server to CCS: 145 146 </p> 147 <pre><message id=""> 148 <gcm xmlns="google:mobile:data"> 149 { 150 "to":"REGISTRATION_ID", // "to" replaces "registration_ids" 151 "message_id":"m-1366082849205" // new required field 152 "data": 153 { 154 "hello":"world", 155 } 156 "time_to_live":"600", 157 "delay_while_idle": true/false 158 } 159 </gcm> 160 </message> 161 </pre> 162 163 <p>Here is an XMPP stanza containing the ACK/NACK message from CCS to 3rd-party server: 164 </p> 165 <pre><message id=""> 166 <gcm xmlns="google:mobile:data"> 167 { 168 "from":"REGID", 169 "message_id":"m-1366082849205" 170 "message_type":"ack" 171 } 172 </gcm> 173 </message> 174 175 <message id=""> 176 <gcm xmlns="google:mobile:data"> 177 { 178 "from":"REGID", 179 "message_id":"m-1366082849205" 180 "error": ERROR_CODE, 181 "message_type":"nack" 182 } 183 </gcm> 184 </message> 185 </pre> 186 187 <h4>Upstream Messages</h4> 188 189 <p>Using CCS and the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> API, you can send messages from a user's device to the cloud.</p> 190 191 <p>Here is how you send an upstream message using the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> API. For a complete example, see <a href="gs.html#gs_example">Getting Started</a>:</p> 192 193 <pre>GoogleCloudMessaging gcm = GoogleCloudMessaging.get(context); 194 String GCM_SENDER_ID = "Your-Sender-ID"; 195 AtomicInteger msgId = new AtomicInteger(); 196 String id = Integer.toString(msgId.incrementAndGet()); 197 Bundle data = new Bundle(); 198 // Bundle data consists of a key-value pair 199 data.putString("hello", "world"); 200 // "time to live" parameter 201 int ttl = [0 seconds, 4 weeks] 202 203 gcm.send(GCM_SENDER_ID + "@gcm.googleapis.com", id, ttl, data); 204 </pre> 205 206 <p>This call generates the necessary XMPP stanza for sending the upstream message. The message goes from the app on the device to CCS to the 3rd-party server. The stanza has the following format:</p> 207 208 <pre><message id=""> 209 <gcm xmlns="google:mobile:data"> 210 { 211 "category":"com.example.yourapp", // to know which app sent it 212 "data": 213 { 214 "hello":"world", 215 }, 216 "message_id":"m-123", 217 "from":"REGID" 218 } 219 </gcm> 220 </message></pre> 221 222 <p>Here is the format of the ACK expected by CCS from 3rd-party servers in response to the above message:</p> 223 224 <pre><message id=""> 225 <gcm xmlns="google:mobile:data"> 226 { 227 "to":"REGID", 228 "message_id":"m-123" 229 "message_type":"ack" 230 } 231 </gcm> 232 </message></pre> 233 234 235 <h2 id="flow">Flow Control</h2> 236 237 <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 message count reaches 1000, the 3rd-party server should stop sending new messages and wait for CCS to acknowledge some of the existing pending messages.</p> 238 239 <p>Conversely, to avoid overloading the 3rd-party server, CCS will stop sending if there are too many unacknowledged messages. Therefore, the 3rd-party server should "ACK" received messages as soon as possible 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 server should continue sending ACKs to avoid blocking delivery of new messages.</p> 240 241 <p>ACKs are only valid within the context of one connection. If the connection is closed before a message can be ACKed, the 3rd-party server should wait for CCS to resend the message before ACKing it again. 242 </p> 243 244
