1 page.title=Implementing GCM Server 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>In this document</h2> 8 9 <ol class="toc"> 10 <li><a href="#choose">Choosing a GCM Connection Server</a></li> 11 <li><a href="#role">Role of the 3rd-party Application Server</a></li> 12 <li><a href="#send-msg">Sending Messages</a> 13 <ol class="toc"> 14 15 <li><a href="#target">Target</a></li> 16 <li><a href="#payload">Payload</a></li> 17 <li><a href="#params">Message parameters</a> 18 </ol> 19 </li> 20 <li><a href="#receive">Receiving Messages</a> </li> 21 </li> 22 23 </ol> 24 25 <h2>See Also</h2> 26 27 <ol class="toc"> 28 <li><a href="gs.html">Getting Started</a></li> 29 <li><a href="client.html">Implementing GCM Client</a></li> 30 <li><a href="ccs.html">Cloud Connection Server (XMPP)</a></li> 31 <li><a href="http.html">HTTP Connection Server</a></li> 32 33 34 </ol> 35 36 </div> 37 </div> 38 39 40 <p>The server side of GCM consists of 2 components:</p> 41 <ul> 42 <li>Google-provided <strong>GCM Connection Servers</strong> 43 take messages from a 3rd-party application server and send them to a GCM-enabled 44 Android application (the "client app") running on a device. For example, 45 Google provides connection servers for <a href="{@docRoot}google/gcm/http.html"> 46 HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP).</li> 47 <li>A <strong>3rd-party application server</strong> that you must implement. This application 48 server sends data to a GCM-enabled Android application via the chosen GCM connection server.</li> 49 </ul> 50 </p> 51 52 <p>Here are the basic steps you follow to implement your 3rd-party app server:</p> 53 54 <ul> 55 <li>Decide which GCM connection server(s) you want to use. Note that if you want to use 56 upstream messaging from your client applications, you must use CCS. For a more detailed 57 discussion of this, see <a href="#choose"> 58 Choosing a GCM Connection Server</a>.</li> 59 <li>Decide how you want to implement your app server. For example: 60 <ul> 61 <li>If you decide to use the HTTP connection server, you can use the 62 GCM server helper library and demo app to help in implementing your app server.</li> 63 <li>If you decide to use the XMPP connection server, you can use 64 the provided Python or Java <a href="http://www.igniterealtime.org/projects/smack/"> 65 Smack</a> demo apps as a starting point.</li> 66 <li>Note that Google AppEngine does not support connections to CCS.</li> 67 </ul> 68 </li> 69 </ul> 70 </li> 71 </ul> 72 73 <p>A full GCM implementation requires both a client implementation and a server 74 implementation. For more 75 information about implementing the client side, see <a href="client.html"> 76 Implementing GCM Client</a>.</p> 77 78 <h2 id="choose">Choosing a GCM Connection Server</h2> 79 80 <p>Currently GCM provides two connection servers: <a href="{@docRoot}google/gcm/http.html"> 81 HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP). You can use them 82 separately or in tandem. CCS messaging differs from GCM HTTP messaging in the following ways:</p> 83 <ul> 84 <li>Upstream/Downstream messages 85 <ul> 86 <li>GCM HTTP: Downstream only: cloud-to-device. </li> 87 <li>CCS: Upstream and downstream (device-to-cloud, cloud-to-device). </li> 88 </ul> 89 </li> 90 <li>Asynchronous messaging 91 <ul> 92 <li>GCM HTTP: 3rd-party app servers send messages as HTTP POST requests and 93 wait for a response. This mechanism is synchronous and causes the sender to block 94 before sending another message.</li> 95 <li>CCS: 3rd-party app servers connect to Google infrastructure using a 96 persistent XMPP connection and send/receive messages to/from all their devices 97 at full line speed. CCS sends acknowledgment or failure notifications (in the 98 form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.</li> 99 </ul> 100 </li> 101 102 <li>JSON 103 <ul> 104 <li>GCM HTTP: JSON messages sent as HTTP POST.</li> 105 <li>CCS: JSON messages encapsulated in XMPP messages.</li> 106 </ul> 107 </li> 108 </ul> 109 110 <h2 id="role">Role of the 3rd-party Application Server</h2> 111 112 <p>Before you can write client Android applications that use the GCM feature, you must 113 have an application server that meets the following criteria:</p> 114 115 <ul> 116 <li>Able to communicate with your client.</li> 117 <li>Able to fire off properly formatted requests to the GCM server.</li> 118 <li>Able to handle requests and resend them as needed, using 119 <a href="http://en.wikipedia.org/wiki/Exponential_backoff">exponential back-off.</a></li> 120 <li>Able to store the API key and client registration IDs. The 121 API key is included in the header of POST requests that send 122 messages.</li> 123 <li>Able to generate message IDs to uniquely identify each message it sends. Message IDs 124 should be unique per sender ID.</li> 125 </ul> 126 127 <h2 id="send-msg">Sending Messages</h2> 128 129 <p>Here is the general sequence of events that occurs when a 3rd-party application 130 server sends a message:</p> 131 <ol> 132 <li>The application server sends a message to GCM servers.</li> 133 <li>Google enqueues and stores the message in case the device is offline.</li> 134 <li>When the device is online, Google sends the message to the device.</li> 135 <li>On the device, the system broadcasts the message to the specified Android 136 application via Intent broadcast with proper permissions, so that only the targeted 137 Android application gets the message. This wakes the Android application up. 138 The Android application does not need to be running beforehand to receive the message.</li> 139 <li>The Android application processes the message. </li> 140 </ol> 141 142 <p>The following sections describe the basic requirements for 143 sending messages.</p> 144 145 <h3 id="target">Target</h3> 146 <p>Required. When your app server sends a message in GCM, it must specify a target.</p> 147 <p>For HTTP you must specify the target as one of:</p> 148 <ul> 149 <li><code>registration_ids</code>: For sending to 1 or more devices (up to 1000). 150 When you send a message to multiple registration IDs, that is called a multicast message.</li> 151 <li><code>notification_key</code>: For sending to multiple devices owned by a single user.</li> 152 </ul> 153 <p>For CCS (XMPP):</p> 154 <ul> 155 <li>You must specify the target as the "to" field, where the "to" 156 field may contain a single registration ID or a notification key. 157 CCS does not support multicast messaging.</li> 158 </ul> 159 <h3 id="payload">Payload</h3> 160 <p>Optional. If you are including a payload in the message, you use the <code>data</code> 161 parameter to include the payload. This applies for both HTTP and CCS.</p> 162 163 <h3 id="params">Message parameters</h3> 164 165 <p>The following table lists the parameters that a 3rd-party app server might 166 include in the JSON messages it sends to a connection server. See the "Where Supported" 167 column for information about which connection servers support that particular 168 parameter.</p> 169 170 <p class="table-caption" id="table1"> 171 <strong>Table 1.</strong> Message parameters.</p> 172 173 <table> 174 <tr> 175 <th>Field</th> 176 <th>Description</th> 177 <th>Where Supported</th> 178 </tr> 179 <td><code>to</code></td> 180 <td>In CCS, used in place of <code>registration_ids</code> to specify the 181 recipient of a message. Its value must be a registration ID. 182 The value is a string. Required.</td> 183 <td>CCS</td> 184 </tr> 185 <tr> 186 <td><code>message_id</code></td> 187 <td>In CCS, uniquely identifies a message in an XMPP connection. The value is a 188 string that uniquely identifies the associated message. The value is a string. Required.</td> 189 <td>CCS</td> 190 </tr> 191 <tr> 192 <td><code>message_type</code></td> 193 <td>In CCS, indicates a special status message, typically sent by the system. 194 However, your app server also uses this parameter to send an 'ack' or 'nack' 195 message back to the CCS connection server. For more discussion of this topic, see 196 <a href="ccs.html">Cloud Connection Server</a>. The value is a string. Optional.</td> 197 <td>CCS</td> 198 <tr> 199 <td><code>registration_ids</code></td> 200 <td>A string array with the list of devices (registration IDs) receiving the 201 message. It must contain at least 1 and at most 1000 registration IDs. To send a 202 multicast message, you must use JSON. For sending a single message to a single 203 device, you could use a JSON object with just 1 registration id, or plain text 204 (see below). A request must include a recipient—this can be either a 205 registration ID, an array of registration IDs, or a {@code notification_key}. 206 Required.</td> 207 <td>HTTP</td> 208 </tr> 209 <tr> 210 <td><code>notification_key</code></td> 211 <td>A string that maps a single user to multiple registration IDs associated 212 with that user. This allows a 3rd-party server to send a single message to 213 multiple app instances (typically on multiple devices) owned by a single user. 214 A 3rd-party server can use {@code notification_key} as the target for a message 215 instead of an individual registration ID (or array of registration IDs). The maximum 216 number of members allowed for a {@code notification_key} is 10. For more discussion 217 of this topic, see <a href="notifications.html">User Notifications</a>. Optional. 218 </td> 219 <td style="width:100px">HTTP. This feature is supported in CCS, but you use it by 220 specifying a notification key in the "to" field.</td> 221 </tr> 222 <tr> 223 <td><code>collapse_key</code></td> 224 <td>An arbitrary string (such as "Updates Available") that is used 225 to collapse a group of like messages 226 when the device is offline, so that only the last message gets sent to the 227 client. This is intended to avoid sending too many messages to the phone when it 228 comes back online. Note that since there is no guarantee of the order in which 229 messages get sent, the "last" message may not actually be the last 230 message sent by the application server. Collapse keys are also called 231 <a href="#s2s">send-to-sync messages</a>. 232 <br> 233 <strong>Note:</strong> GCM allows a maximum of 4 different collapse keys to be 234 used by the GCM server 235 at any given time. In other words, the GCM server can simultaneously store 4 236 different send-to-sync messages per device, each with a different collapse key. 237 If you exceed 238 this number GCM will only keep 4 collapse keys, with no guarantees about which 239 ones they will be. See <a href="adv.html#collapsible">Advanced Topics</a> for more 240 discussion of this topic. Optional.</td> 241 <td>CCS, HTTP</td> 242 </tr> 243 <tr> 244 <td><code>data</code></td> 245 <td>A JSON object whose fields represents the key-value pairs of the message's 246 payload data. If present, the payload data it will be 247 included in the Intent as application data, with the key being the extra's name. 248 For instance, <code>"data":{"score":"3x1"}</code> would result in an intent extra 249 named <code>score</code> whose value is the string <code>3x1</code>. 250 There is no limit on the number of key/value pairs, though there is a limit on 251 the total size of the message (4kb). The values could be any JSON object, but we 252 recommend using strings, since the values will be converted to strings in the GCM 253 server anyway. If you want to include objects or other non-string data types 254 (such as integers or booleans), you have to do the conversion to string yourself. 255 Also note that the key cannot be a reserved word (<code>from</code> or any word 256 starting with <code>google.</code>). To complicate things slightly, there are 257 some reserved words (such as <code>collapse_key</code>) that are technically 258 allowed in payload data. However, if the request also contains the word, the 259 value in the request will overwrite the value in the payload data. Hence using 260 words that are defined as field names in this table is not recommended, even in 261 cases where they are technically allowed. Optional.</td> 262 <td>CCS, HTTP</td> 263 </tr> 264 <tr> 265 <td><code>delay_while_idle</code></td> 266 <td>If included, indicates that the message should not be sent immediately 267 if the device is idle. The server will wait for the device to become active, and 268 then only the last message for each <code>collapse_key</code> value will be 269 sent. The default value is <code>false</code>, and must be a JSON boolean. Optional.</td> 270 <td>CCS, HTTP</td> 271 </tr> 272 <tr> 273 <td><code>time_to_live</code></td> 274 <td>How long (in seconds) the message should be kept on GCM storage if the 275 device is offline. Optional (default time-to-live is 4 weeks, and must be set as 276 a JSON number).</td> 277 <td>CCS, HTTP</td> 278 </tr> 279 <tr> 280 <td><code>restricted_package_name</code></td> 281 <td>A string containing the package name of your application. When set, messages 282 will only be sent to registration IDs that match the package name. Optional. 283 </td> 284 <td>HTTP</td> 285 </tr> 286 <tr> 287 <td><code>dry_run</code></td> 288 <td>If included, allows developers to test their request without actually 289 sending a message. Optional. The default value is <code>false</code>, and must 290 be a JSON boolean. 291 </td> 292 <td>HTTP</td> 293 </tr> 294 </table> 295 296 <p>If you want to test your request (either JSON or plain text) without delivering 297 the message to the devices, you can set an optional HTTP or JSON parameter called 298 <code>dry_run</code> with the value <code>true</code>. The result will be almost 299 identical to running the request without this parameter, except that the message 300 will not be delivered to the devices. Consequently, the response will contain fake 301 IDs for the message and multicast fields.</p> 302 303 <h3 id="plain-text">Plain text (HTTP only)</h3> 304 305 <p>If you are using plain text instead of JSON, the message fields must be set as 306 HTTP parameters sent in the body, and their syntax is slightly different, as 307 described below: 308 <table> 309 <tr> 310 <th>Field</th> 311 <th>Description</th> 312 </tr> 313 <tr> 314 <td><code>registration_id</code></td> 315 <td>Must contain the registration ID of the single device receiving the message. 316 Required.</td> 317 </tr> 318 <tr> 319 <td><code>collapse_key</code></td> 320 <td>Same as JSON (see previous table). Optional.</td> 321 </tr> 322 <tr> 323 <td><code>data.<key></code></td> 324 325 <td>Payload data, expressed as parameters prefixed with <code>data.</code> and 326 suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would 327 result in an intent extra named <code>score</code> whose value is the string 328 <code>3x1</code>. There is no limit on the number of key/value parameters, though 329 there is a limit on the total size of the message. Also note that the key cannot 330 be a reserved word (<code>from</code> or any word starting with 331 <code>google.</code>). To complicate things slightly, there are some reserved words 332 (such as <code>collapse_key</code>) that are technically allowed in payload data. 333 However, if the request also contains the word, the value in the request will 334 overwrite the value in the payload data. Hence using words that are defined as 335 field names in this table is not recommended, even in cases where they are 336 technically allowed. Optional.</td> 337 338 </tr> 339 <tr> 340 <td><code>delay_while_idle</code></td> 341 <td>Should be represented as <code>1</code> or <code>true</code> for 342 <code>true</code>, anything else for <code>false</code>. Optional. The default 343 value is <code>false</code>.</td> 344 </tr> 345 <tr> 346 <td><code>time_to_live</code></td> 347 <td>Same as JSON (see previous table). Optional.</td> 348 </tr> 349 <tr> 350 <td><code>restricted_package_name</code></td> 351 <td>Same as JSON (see previous table). Optional. 352 </td> 353 </tr> 354 <tr> 355 <td><code>dry_run</code></td> 356 <td>Same as JSON (see previous table). Optional. 357 </td> 358 </tr> 359 </table> 360 361 <h2 id="receive">Receiving Messages</h2> 362 363 <p>This is the sequence of events that occurs when an Android application 364 installed on a mobile device receives a message:</p> 365 366 <ol> 367 <li>The system receives the incoming message and extracts the raw key/value 368 pairs from the message payload, if any.</li> 369 <li>The system passes the key/value pairs to the targeted Android application 370 in a <code>com.google.android.c2dm.intent.RECEIVE</code> Intent as a set of 371 extras.</li> 372 <li>The Android application extracts the raw data 373 from the <code>com.google.android.c2dm.intent.RECEIVE</code><code> </code>Intent 374 by key and processes the data.</li> 375 </ol> 376 377 <p>See the documentation for each connection server for more detail on how it 378 handles responses.</p> 379
