• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.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
25developers  send data from servers to their Android applications on  Android
26devices, and upstream messages from the user's device back to the cloud.
27This could be a lightweight message telling the Android application
28that there is new data to be fetched from the server (for instance, a "new email"
29notification informing the application that it is out of sync with the back end),
30or it could be a message containing up to 4kb of payload
31data (so apps like instant messaging can consume the message directly). The GCM
32service handles all aspects  of queueing of messages and delivery to the target
33Android 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
39Messaging (GCM):</p>
40
41<ul>
42  <li>It allows 3rd-party application servers to send messages to
43their Android applications.</li>
44  <li>Using the <a href="ccs.html">GCM Cloud Connection Server</a>, you can receive
45upstream messages from the user's device.</li>
46  <li>An Android application on an Android device doesn't need to be running to receive
47messages. The system will wake up the Android application via Intent broadcast
48when the  message arrives, as long as the application is set up with the proper
49broadcast receiver and permissions.</li>
50  <li>It does not provide any  built-in user interface or other handling for
51message data. GCM  simply passes raw message data received straight to the
52Android application,  which has full control of how to handle it. For example, the
53application might post a notification, display a custom user interface, or
54silently sync data.</li>
55  <li>It requires devices running Android 2.2 or higher that also have the
56Google Play Store application installed, or or an emulator running Android 2.2
57with Google APIs. However, you are not limited to deploying your
58Android applications through Google Play Store.</li>
59  <li>It uses an existing connection for Google services. For pre-3.0 devices,
60this requires users to
61set up their Google account on their mobile devices. A Google account is not a
62requirement 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
68divided into these categories:</p>
69<ul>
70  <li><strong>Components</strong> &mdash; The entities that play a primary role in
71GCM.</li>
72  <li><strong>Credentials</strong> &mdash; The IDs and tokens that are used in
73different stages of GCM to ensure that all parties have been authenticated, and
74that 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
88have at least one logged in Google account if the device is running a version
89lower than Android 4.0.4. Alternatively, for testing you can use an emulator
90running 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
95GCM. The 3rd-party application server sends data to an
96Android 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
101application 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
110ID is used in the <a href="#register">registration process</a> to identify a
1113rd-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
116is identified by the package name from the <a href="client.html#manifest">manifest</a>.
117This  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
122it to receive messages. Once the Android application has the registration ID, it sends
123it to the 3rd-party application server, which uses it to identify each device
124that has registered to receive messages for a given Android application. In other words,
125a registration ID is tied to a particular Android application running on a particular
126device. 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>,
131you should explicitly avoid backing up registration IDs. When you back up
132a device, apps back up shared prefs indiscriminately. If you don't explicitly
133exclude the GCM registration ID, it could get reused on a new device,
134which 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
140account 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
145server that gives the application server authorized access to Google services.
146The 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
154connection server, a 3rd-party app server that interacts with the connection
155server, 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
166a 3rd-party application server and send these messages to a
167GCM-enabled Android application (the &quot;client app&quot;) running on a device.
168Currently Google provides connection servers for <a href="http.html">HTTP</a>
169and <a href="ccs.html">XMPP</a>.</li>
170  <li>The <strong>3rd-Party Application Server</strong> is a component that you
171implement to work with your chosen GCM connection server(s). App servers send
172messages to a GCM connection server; the connection server enqueues and stores the
173message, and then sends it to the device when the device is online.
174For 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
176on a device. To receive GCM messages, this app must register with GCM and get a
177registration ID. If you are using the <a href="ccs.html">XMPP</a> (CCS) connection
178server, the client app can send "upstream" messages back to the connection server.
179For 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
187mobile device registers to receive messages.</li>
188
189  <li><a href="#push-process">Send a message</a>. A 3rd-party application
190server sends messages to the device.</li>
191  <li><a href="#receiving">Receive a message</a>. An Android application
192receives 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
200calls 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>.
203The {@code register()} method returns a registration ID. The Android
204application should store this ID for later use (for instance,
205to 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
211message:</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
216offline.</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
219Android application via Intent broadcast with proper permissions, so that only the
220targeted Android application gets the message. This wakes the Android application up. The
221Android 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
223non-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
228messages.</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
233installed 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
237pairs from the message payload, if any.</li>
238  <li>The system passes the key/value pairs to the targeted Android application
239in a <code>com.google.android.c2dm.intent.RECEIVE</code> Intent as a set of
240extras.</li>
241  <li>The Android application extracts the raw data
242from the <code>com.google.android.c2dm.intent.RECEIVE</code><code> </code>Intent
243by key and processes the data.</li>
244</ol>
245
246
247