Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 1 | page.title=Overview |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 2 | @jd:body |
| 3 | |
| 4 | <div id="qv-wrapper"> |
| 5 | <div id="qv"> |
| 6 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 7 | <h2>In this document</h2> |
| 8 | |
| 9 | <ol class="toc"> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 10 | <li><a href="#key">Key Concepts</a></li> |
| 11 | <li><a href="#arch">Architectural Overview</a></li> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 12 | <li><a href="#lifecycle">Lifecycle Flow</a></li> |
| 13 | <li><a href="#reg">Register to enable GCM</a></li> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 14 | </ol> |
| 15 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 16 | </div> |
| 17 | </div> |
| 18 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 19 | <p>Google Cloud Messaging (GCM) is a free service that enables developers |
| 20 | to send downstream messages (from servers to GCM-enabled client apps), and |
| 21 | upstream messages (from the GCM-enabled client apps to servers). |
| 22 | This could be a lightweight message telling the client app |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 23 | that there is new data to be fetched from the server (for instance, a "new email" |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 24 | notification informing the app that it is out of sync with the back end), |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 25 | or it could be a message containing up to 4kb of payload |
Katie McCormick | 4e11e3e | 2012-08-29 15:10:00 -0700 | [diff] [blame] | 26 | data (so apps like instant messaging can consume the message directly). The GCM |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 27 | service handles all aspects of queueing of messages and delivery to and from |
| 28 | the target client app.</p> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 29 | |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 30 | |
| 31 | <h2 id="key">Key Concepts</h2> |
| 32 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 33 | <p>This table summarizes the key terms and concepts involved in GCM. It is |
| 34 | divided into these categories:</p> |
| 35 | <ul> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 36 | <li><strong>Components</strong> — The entities that play a primary role in |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 37 | GCM.</li> |
| 38 | <li><strong>Credentials</strong> — The IDs and tokens that are used in |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 39 | GCM to ensure that all parties have been authenticated, and |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 40 | that the message is going to the correct place.</li> |
| 41 | </ul> |
| 42 | |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 43 | <p class="table-caption" id="table1"> |
| 44 | <strong>Table 1.</strong> GCM components and credentials.</p> |
| 45 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 46 | <table> |
| 47 | <tr> |
| 48 | <th colspan="2">Components</th> |
| 49 | </tr> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 50 | <tr> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 51 | <td><strong>GCM Connection Servers</strong></td> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 52 | <td>The Google-provided servers involved in sending messages between the |
| 53 | 3rd-party app server and the client app.</td> |
| 54 | </tr> |
| 55 | <tr> |
| 56 | <td><strong>Client App</strong></td> |
| 57 | <td>A GCM-enabled client app that communicates with a 3rd-party app server.</td> |
| 58 | </tr> |
| 59 | <tr> |
| 60 | <td><strong>3rd-party App Server</strong></td> |
| 61 | <td>An app server that you write as part of implementing |
| 62 | GCM. The 3rd-party app server sends data to a client app via |
| 63 | the GCM connection server.</td> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 64 | </tr> |
| 65 | <tr> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 66 | <th colspan="2">Credentials</th> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 67 | </tr> |
| 68 | <tr> |
Katie McCormick | 6b37262 | 2013-11-15 16:02:58 -0800 | [diff] [blame] | 69 | <td id="senderid"><strong>Sender ID</strong></td> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 70 | <td>A project number you acquire from the API console, as described in |
| 71 | <a href="gs.html#create-proj">Getting Started</a>. The sender |
| 72 | ID is used in the <a href="#register">registration process</a> to identify a |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 73 | 3rd-party app server that is permitted to send messages to the client app.</td> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 74 | </tr> |
| 75 | <tr> |
Katie McCormick | 6b37262 | 2013-11-15 16:02:58 -0800 | [diff] [blame] | 76 | <td id="apikey"><strong>Sender Auth Token</strong></td> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 77 | <td>An API key that is saved on the 3rd-party app |
| 78 | server that gives the app server authorized access to Google services. |
| 79 | The API key is included in the header of POST requests. |
| 80 | </td> |
| 81 | </tr> |
| 82 | <tr> |
| 83 | <td><strong>Application ID</strong></td> |
| 84 | <td>The client app that is registering to receive messages. How this is implemented |
| 85 | is platform-dependent. For example, an Android app |
| 86 | is identified by the package name from the <a href="client.html#manifest">manifest</a>. |
| 87 | This ensures that the messages are targeted to the correct Android app.</td> |
| 88 | </tr> |
| 89 | <tr> |
| 90 | <td><strong>Registration ID</strong></td> |
| 91 | <td>An ID issued by the GCM servers to the client app that allows |
| 92 | it to receive messages. Note that registration IDs must be kept secret. |
| 93 | |
| 94 | </td> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 95 | </tr> |
kmccormick | eeaac81 | 2013-04-18 10:57:59 -0700 | [diff] [blame] | 96 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 97 | </table> |
| 98 | |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 99 | <h2 id="arch">Architectural Overview</h2> |
| 100 | |
| 101 | <p>A GCM implementation includes a Google-provided |
| 102 | connection server, a 3rd-party app server that interacts with the connection |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 103 | server, and a GCM-enabled client app. For example, this diagram shows GCM |
| 104 | communicating with a client app on an Android device:</p> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 105 | |
| 106 | <img src="{@docRoot}images/gcm/GCM-arch.png"> |
| 107 | |
| 108 | <p class="img-caption"> |
| 109 | <strong>Figure 1.</strong> GCM Architecture. |
| 110 | </p> |
| 111 | |
| 112 | <p>This is how these components interact:</p> |
| 113 | <ul> |
| 114 | <li>Google-provided <strong>GCM Connection Servers</strong> take messages from |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 115 | a 3rd-party app server and send these messages to a |
| 116 | GCM-enabled client app (the "client app"). |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 117 | Currently Google provides connection servers for <a href="http.html">HTTP</a> |
| 118 | and <a href="ccs.html">XMPP</a>.</li> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 119 | <li>The <strong>3rd-Party App Server</strong> is a component that you |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 120 | implement to work with your chosen GCM connection server(s). App servers send |
| 121 | messages to a GCM connection server; the connection server enqueues and stores the |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 122 | message, and then sends it to the client app. |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 123 | For more information, see <a href="server.html">Implementing GCM Server</a>.</li> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 124 | <li>The <strong>Client App</strong> is a GCM-enabled client app. |
| 125 | To receive GCM messages, this app must register with GCM and get a |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 126 | registration ID. If you are using the <a href="ccs.html">XMPP</a> (CCS) connection |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 127 | server, the client app can send "upstream" messages back to the 3rd-party app server. |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 128 | For more information on how to implement the client app, see |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 129 | the documentation for your platform.</li> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 130 | </ul> |
| 131 | |
| 132 | <h2 id="lifecycle">Lifecycle Flow</h2> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 133 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 134 | <ul> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 135 | <li><strong>Register to enable GCM</strong>. A client app registers to receive messages. |
| 136 | For more discussion, see <a href="#register">Register to enable GCM</a>.</li> |
| 137 | <li><strong>Send and receive downstream messages</strong>. |
| 138 | <ul> |
| 139 | <li>Send a message. A 3rd-party app server sends messages to the client app: |
| 140 | <ol> |
| 141 | <li>The 3rd-party app server <a href="server.html#send-msg">sends a message</a> |
| 142 | to GCM connection servers.</li> |
| 143 | <li>The GCM connection server enqueues and stores the message if the device is offline.</li> |
| 144 | <li>When the device is online, the GCM connection server sends the message to the device. </li> |
| 145 | <li>On the device, the client app receives the message according to the platform-specific implementation. |
| 146 | See your platform-specific documentation for details.</li> |
| 147 | </ol> |
| 148 | </li> |
| 149 | <li>Receive a message. A client app |
| 150 | receives a message from a GCM server. See your platform-specific documentation for details |
| 151 | on how a client app in that environment processes the messages it receives.</li> |
| 152 | </ul> |
| 153 | </li> |
Katie McCormick | 0ab9326 | 2013-11-01 18:10:51 -0700 | [diff] [blame] | 154 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 155 | <li><strong>Send and receive upstream messages</strong>. This feature is only available if |
| 156 | you're using the <a href="ccs.html">XMPP Cloud Connection Server</a> (CCS). |
| 157 | <ul> |
| 158 | <li>Send a message. A client app sends messages to the 3rd-party app server: |
| 159 | <ol> |
| 160 | <li>On the device, the client app sends messages to XMPP (CCS).See your platform-specific |
| 161 | documentation for details on how a client app can send a message to XMPP (CCS).</li> |
| 162 | <li>XMPP (CCS) enqueues and stores the message if the server is disconnected.</li> |
| 163 | <li>When the 3rd-party app server is re-connected, XMPP (CCS) sends the message to the 3rd-party app server.</li> |
| 164 | </ol> |
| 165 | </li> |
| 166 | <li>Receive a message. A 3rd-party app server receives a message from XMPP (CCS) and then does the following: |
| 167 | <ol> |
| 168 | <li>Parses the message header to verify client app sender information. |
| 169 | <li>Sends "ack" to GCM XMPP connection server to acknowledge receiving the message. |
| 170 | <li>Optionally parses the message payload, as defined by the client app. |
| 171 | </ol> |
| 172 | </li> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 173 | </ul> |
| 174 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 175 | </li> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 176 | |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 177 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 178 | </ul> |
| 179 | |
| 180 | <h2 id="reg">Register to enable GCM</h2> |
| 181 | |
| 182 | <p>Regardless of the platform you're developing on, the first step |
| 183 | a client app must do is register with GCM. This section covers some of the general |
| 184 | best practices for registration and unregistration. See your platform-specific docs for |
| 185 | details on writing a GCM-enabled client app on that platform.</p> |
| 186 | |
| 187 | <h3 id="reg-state">Keeping the Registration State in Sync</h3> |
| 188 | <p>Whenever the app registers as described in |
| 189 | <a href="{@docRoot}google/gcm/client.html">Implementing GCM Client</a>, |
| 190 | it should save the registration ID for future use, pass it to the |
| 191 | 3rd-party server to complete the registration, and keep track of |
| 192 | whether the server completed the registration. If the server fails |
| 193 | to complete the registration, the client app should retry passing the |
| 194 | registration ID to 3rd-party app server to complete the registration. |
| 195 | If this continues to fail, the client app should unregister from GCM.</p> |
| 196 | |
| 197 | <p>There are also two other scenarios that require special care:</p> |
| 198 | <ul> |
| 199 | <li>Client app update</li> |
| 200 | <li>Backup and restore |
| 201 | </li> |
| 202 | </ul> |
| 203 | <p><bold>Client app update:</bold> When a client app is updated, it should invalidate its existing registration |
| 204 | ID, as it is not guaranteed to work with the new version. The recommended way to achieve |
| 205 | this validation is by storing the current app version when a registration |
| 206 | ID is stored. Then when the app starts, compare the stored value with |
| 207 | the current app version. If they do not match, invalidate the stored data |
| 208 | and start the registration process again.</p> |
| 209 | |
| 210 | <p><bold>Backup and restore: </bold> You should not save the registration ID when an app is |
| 211 | backed up. This is because the registration ID could become invalid by the time |
| 212 | the app is restored, which would put the app in an invalid state |
| 213 | (that is, the app thinks it is registered, but the server and GCM do not |
| 214 | store that registration ID anymore—thus the app will not get more |
| 215 | messages). The best practice is to initiate the registration process as if the app has been |
| 216 | installed for the first time.</p> |
| 217 | |
| 218 | <h4 id="canonical">Canonical IDs</h4> |
| 219 | <p>If a bug in the app triggers multiple |
| 220 | registrations for the same device, it can be hard to reconcile state and you might |
| 221 | end up with duplicate messages.</p> |
| 222 | <p>GCM provides a facility called "canonical registration IDs" to easily |
| 223 | recover from these situations. A canonical registration ID is defined to be the ID |
| 224 | of the last registration requested by your app. This is the ID that the |
| 225 | server should use when sending messages to the device.</p> |
| 226 | <p>If later on you try to send a message using a different registration ID, GCM |
| 227 | will process the request as usual, but it will include the canonical registration |
| 228 | ID in the <code>registration_id</code> field of the response. Make sure to replace |
| 229 | the registration ID stored in your server with this canonical ID, as eventually |
| 230 | the ID you're using will stop working.</p> |
| 231 | |
| 232 | <h3 id="retry">Automatic Retry Using Exponential Back-Off</h3> |
| 233 | |
| 234 | <p>When registration or unregistration fails, the app should retry the failed operation.</p> |
| 235 | <p>In the simplest case, if your app attempts to register and GCM is not a |
| 236 | fundamental part of the app, the app could simply ignore the error |
| 237 | and try to register again the next time it starts. Otherwise, it should retry the |
| 238 | previous operation using exponential back-off. In exponential back-off, each time |
| 239 | there is a failure, it should wait twice the previous amount of time before trying |
| 240 | again. |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 241 | </p> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 242 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 243 | <h3 id="unreg">Unregistration</h3> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 244 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 245 | <p>This section explains when you should unregister in GCM and what happens |
| 246 | when you do.</p> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 247 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 248 | <h4 id="unreg-why">Why you should rarely unregister</h4> |
| 249 | |
| 250 | <p>You should only need to unregister in rare cases, such as |
| 251 | if you want an app to stop receiving messages, or if you suspect that the registration ID has |
| 252 | been compromised. In general, once an app has a registration ID, you shouldn't need |
| 253 | to change it.</p> |
| 254 | |
| 255 | <p>In particular, you should never unregister your app as a mechanism for |
| 256 | logout or for switching between users, for the following reasons:</p> |
| 257 | |
| 258 | <ul> |
| 259 | <li>A registration ID isn't associated with a particular |
| 260 | logged in user. If you unregister and then re-register, GCM may return the same |
| 261 | ID or a different ID—there's no guarantee either way.</li> |
| 262 | |
| 263 | <li>Unregistration may take up to 5 minutes to propagate.</li> |
| 264 | <li>After unregistration, re-registration may again take up to 5 minutes to |
| 265 | propagate. During this time messages may be rejected due to the state of being |
| 266 | unregistered, and after all this, messages may still go to the wrong user.</li> |
| 267 | </ul> |
| 268 | |
| 269 | |
| 270 | <p>To make sure that messages go to the intended user:</p> |
| 271 | |
| 272 | <ul> |
| 273 | <li>Your app server can maintain a mapping between the current user |
| 274 | and the registration ID.</li> |
| 275 | <li>The app can then check to ensure that messages it |
| 276 | receives match the logged in user.</li> |
| 277 | </ul> |
| 278 | |
| 279 | |
| 280 | <h4 id="unreg-how">How unregistration works</h4> |
| 281 | |
Eric Gilmore | f1598d1 | 2015-03-17 15:46:15 -0700 | [diff] [blame] | 282 | <p>A client app can be automatically unregistered after it is uninstalled. |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 283 | However, this process does not happen right away. What happens in |
| 284 | this scenario is as follows:</p> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 285 | <ol> |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 286 | <li>The end user uninstalls the client app.</li> |
| 287 | <li>The 3rd-party app server sends a message to GCM server.</li> |
| 288 | <li>The GCM server sends the message to the GCM client on the device.</li> |
| 289 | <li>The GCM client on the device receives the message and detects that the client app has been |
| 290 | uninstalled; the detection details depend on the platform on which the client app is running. |
| 291 | </li> |
| 292 | <li>The GCM client on the device informs the GCM server that the client app was uninstalled.</li> |
| 293 | <li>The GCM server marks the registration ID for deletion.</li> |
| 294 | <li>The 3rd-party app server sends a message to GCM.</li> |
| 295 | <li>The GCM returns a <code>NotRegistered</code> error message to the 3rd-party app server.</li> |
| 296 | <li>The 3rd-party app server deletes the registration ID. |
| 297 | </li> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 298 | </ol> |
| 299 | |
kmccormick | 0137175 | 2014-12-12 15:00:37 -0800 | [diff] [blame] | 300 | <p>Note that it might take a while for the registration ID be completely removed |
| 301 | from GCM. Thus it is possible that messages sent during step 7 above gets a valid |
| 302 | message ID as response, even though the message will not be delivered to the client app. |
| 303 | Eventually, the registration ID will be removed and the server will get a |
| 304 | <code>NotRegistered</code> error, without any further action being required from |
| 305 | the 3rd-party server (this scenario happens frequently while an app is |
| 306 | being developed and tested).</p> |
Katie McCormick | 76c6d86 | 2012-06-25 09:56:29 -0700 | [diff] [blame] | 307 | |