1 page.title=Overview 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="#key">Key Concepts</a></li> 11 <li><a href="#arch">Architectural Overview</a></li> 12 <li><a href="#lifecycle">Lifecycle Flow</a> 13 <ol class="toc"> 14 <li><a href="#register">Enable GCM</a></li> 15 <li><a href="#push-process">Send a message</a></li> 16 <li><a href="#receiving">Receive a message</a></li> 17 </ol> 18 </li> 19 </ol> 20 21 </div> 22 </div> 23 24 <p>Google Cloud Messaging for Android (GCM) is a free service that helps 25 developers send data from servers to their Android applications on Android 26 devices, and upstream messages from the user's device back to the cloud. 27 This could be a lightweight message telling the Android application 28 that there is new data to be fetched from the server (for instance, a "new email" 29 notification informing the application that it is out of sync with the back end), 30 or it could be a message containing up to 4kb of payload 31 data (so apps like instant messaging can consume the message directly). The GCM 32 service handles all aspects of queueing of messages and delivery to the target 33 Android application running on the target device.</p> 34 35 <p class="note"> To jump right into using GCM with your Android 36 applications, see <a href="gs.html">Getting Started</a>.</p> 37 38 <p>Here are the primary characteristics of Google Cloud 39 Messaging (GCM):</p> 40 41 <ul> 42 <li>It allows 3rd-party application servers to send messages to 43 their Android applications.</li> 44 <li>Using the <a href="ccs.html">GCM Cloud Connection Server</a>, you can receive 45 upstream messages from the user's device.</li> 46 <li>An Android application on an Android device doesn't need to be running to receive 47 messages. The system will wake up the Android application via Intent broadcast 48 when the message arrives, as long as the application is set up with the proper 49 broadcast receiver and permissions.</li> 50 <li>It does not provide any built-in user interface or other handling for 51 message data. GCM simply passes raw message data received straight to the 52 Android application, which has full control of how to handle it. For example, the 53 application might post a notification, display a custom user interface, or 54 silently sync data.</li> 55 <li>It requires devices running Android 2.2 or higher that also have the 56 Google Play Store application installed, or or an emulator running Android 2.2 57 with Google APIs. However, you are not limited to deploying your 58 Android applications through Google Play Store.</li> 59 <li>It uses an existing connection for Google services. For pre-3.0 devices, 60 this requires users to 61 set up their Google account on their mobile devices. A Google account is not a 62 requirement on devices running Android 4.0.4 or higher.</li> 63 </ul> 64 65 <h2 id="key">Key Concepts</h2> 66 67 <p>This table summarizes the key terms and concepts involved in GCM. It is 68 divided into these categories:</p> 69 <ul> 70 <li><strong>Components</strong> — The entities that play a primary role in 71 GCM.</li> 72 <li><strong>Credentials</strong> — The IDs and tokens that are used in 73 different stages of GCM to ensure that all parties have been authenticated, and 74 that the message is going to the correct place.</li> 75 </ul> 76 77 <p class="table-caption" id="table1"> 78 <strong>Table 1.</strong> GCM components and credentials.</p> 79 80 <table> 81 <tr> 82 <th colspan="2">Components</th> 83 </tr> 84 <tr> 85 <td width="165"><strong>Client App</strong></td> 86 <td width="1176">The GCM-enabled Android application that is running on a 87 device. This must be a 2.2 Android device that has Google Play Store installed, and it must 88 have at least one logged in Google account if the device is running a version 89 lower than Android 4.0.4. Alternatively, for testing you can use an emulator 90 running Android 2.2 with Google APIs.</td> 91 </tr> 92 <tr> 93 <td><strong>3rd-party Application Server</strong></td> 94 <td>An application server that you write as part of implementing 95 GCM. The 3rd-party application server sends data to an 96 Android application on the device via the GCM connection server.</td> 97 </tr> 98 <tr> 99 <td><strong>GCM Connection Servers</strong></td> 100 <td>The Google-provided servers involved in taking messages from the 3rd-party 101 application server and sending them to the device. </td> 102 </tr> 103 <tr> 104 <th colspan="2">Credentials</th> 105 </tr> 106 <tr> 107 <td id="senderid"><strong>Sender ID</strong></td> 108 <td>A project number you acquire from the API console, as described in 109 <a href="gs.html#create-proj">Getting Started</a>. The sender 110 ID is used in the <a href="#register">registration process</a> to identify a 111 3rd-party application server that is permitted to send messages to the device.</td> 112 </tr> 113 <tr> 114 <td><strong>Application ID</strong></td> 115 <td>The Android application that is registering to receive messages. The Android application 116 is identified by the package name from the <a href="client.html#manifest">manifest</a>. 117 This ensures that the messages are targeted to the correct Android application.</td> 118 </tr> 119 <tr> 120 <td><strong>Registration ID</strong></td> 121 <td>An ID issued by the GCM servers to the Android application that allows 122 it to receive messages. Once the Android application has the registration ID, it sends 123 it to the 3rd-party application server, which uses it to identify each device 124 that has registered to receive messages for a given Android application. In other words, 125 a registration ID is tied to a particular Android application running on a particular 126 device. Note that registration IDs must be kept secret. 127 <br/> 128 <br/> 129 <strong>Note:</strong> If you use 130 <a href="https://developer.android.com/google/backup/index.html">backup and restore</a>, 131 you should explicitly avoid backing up registration IDs. When you back up 132 a device, apps back up shared prefs indiscriminately. If you don't explicitly 133 exclude the GCM registration ID, it could get reused on a new device, 134 which would cause delivery errors. 135 </td> 136 </tr> 137 <tr> 138 <td><strong>Google User Account</strong></td> 139 <td>For GCM to work, the mobile device must include at least one Google 140 account if the device is running a version lower than Android 4.0.4.</td> 141 </tr> 142 <tr> 143 <td id="apikey"><strong>Sender Auth Token</strong></td> 144 <td>An API key that is saved on the 3rd-party application 145 server that gives the application server authorized access to Google services. 146 The API key is included in the header of POST requests that send messages.</td> 147 </tr> 148 149 </table> 150 151 <h2 id="arch">Architectural Overview</h2> 152 153 <p>A GCM implementation includes a Google-provided 154 connection server, a 3rd-party app server that interacts with the connection 155 server, and a GCM-enabled client app running on an Android device:</p> 156 157 <img src="{@docRoot}images/gcm/GCM-arch.png"> 158 159 <p class="img-caption"> 160 <strong>Figure 1.</strong> GCM Architecture. 161 </p> 162 163 <p>This is how these components interact:</p> 164 <ul> 165 <li>Google-provided <strong>GCM Connection Servers</strong> take messages from 166 a 3rd-party application server and send these messages to a 167 GCM-enabled Android application (the "client app") running on a device. 168 Currently Google provides connection servers for <a href="http.html">HTTP</a> 169 and <a href="ccs.html">XMPP</a>.</li> 170 <li>The <strong>3rd-Party Application Server</strong> is a component that you 171 implement to work with your chosen GCM connection server(s). App servers send 172 messages to a GCM connection server; the connection server enqueues and stores the 173 message, and then sends it to the device when the device is online. 174 For more information, see <a href="server.html">Implementing GCM Server</a>.</li> 175 <li>The <strong>Client App</strong> is a GCM-enabled Android application running 176 on a device. To receive GCM messages, this app must register with GCM and get a 177 registration ID. If you are using the <a href="ccs.html">XMPP</a> (CCS) connection 178 server, the client app can send "upstream" messages back to the connection server. 179 For more information on how to implement the client app, see 180 <a href="client.html">Implementing GCM Client</a>.</li> 181 </ul> 182 183 <h2 id="lifecycle">Lifecycle Flow</h2> 184 185 <ul> 186 <li><a href="#register">Enable GCM</a>. An Android application running on a 187 mobile device registers to receive messages.</li> 188 189 <li><a href="#push-process">Send a message</a>. A 3rd-party application 190 server sends messages to the device.</li> 191 <li><a href="#receiving">Receive a message</a>. An Android application 192 receives a message from a GCM server.</li> 193 </ul> 194 195 <p>These processes are described in more detail below.</p> 196 197 <h3 id="register">Enable GCM</h3> 198 199 <p>The first time the Android application needs to use the messaging service, it 200 calls the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> 201 {@code GoogleCloudMessaging}</a> method {@code register()}, as discussed in 202 <a href="client.html">Implementing GCM Client</a>. 203 The {@code register()} method returns a registration ID. The Android 204 application should store this ID for later use (for instance, 205 to check in <code>onCreate()</code> if it is already registered). 206 </p> 207 208 <h3 id="push-process">Send a message</h3> 209 210 <p>Here is the sequence of events that occurs when the application server sends a 211 message:</p> 212 213 <ol> 214 <li>The application server sends a message to GCM servers.</li> 215 <li>Google enqueues and stores the message in case the device is 216 offline.</li> 217 <li>When the device is online, Google sends the message to the device. </li> 218 <li>On the device, the system broadcasts the message to the specified 219 Android application via Intent broadcast with proper permissions, so that only the 220 targeted Android application gets the message. This wakes the Android application up. The 221 Android application does not need to be running beforehand to receive the message.</li> 222 <li>The Android application processes the message. If the Android application is doing 223 non-trivial processing, you may want to grab a 224 {@link android.os.PowerManager.WakeLock} and do any processing in a service.</li> 225 </ol> 226 227 <p> An Android application can unregister GCM if it no longer wants to receive 228 messages.</p> 229 230 <h3 id="receiving">Receive a message</h3> 231 232 <p>This is the sequence of events that occurs when an Android application 233 installed on a mobile device receives a message:</p> 234 235 <ol> 236 <li>The system receives the incoming message and extracts the raw key/value 237 pairs from the message payload, if any.</li> 238 <li>The system passes the key/value pairs to the targeted Android application 239 in a <code>com.google.android.c2dm.intent.RECEIVE</code> Intent as a set of 240 extras.</li> 241 <li>The Android application extracts the raw data 242 from the <code>com.google.android.c2dm.intent.RECEIVE</code><code> </code>Intent 243 by key and processes the data.</li> 244 </ol> 245 246 247
