1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
page.title=Migration
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Understand the differences between GCM and C2DM.</li>
<li>Learn how to migrate an app from C2DM to GCM.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#history">Historical Overview</a></li>
<li><a href="#diffs">How is GCM Different from C2DM?</a></li>
<li><a href="#migrating">Migrating Your Apps</a>
<ol>
<li><a href="#client">Client changes</a></li>
<li><a href="#server">Server changes</a></li>
</ol>
</li>
</ol>
</div>
</div>
<p>Android Cloud to Device Messaging (C2DM) is deprecated. The C2DM service will continue to be maintained in the short term, but C2DM will accept no new users, and it will grant no new quotas. <strong>C2DM developers are strongly encouraged to move to Google Cloud Messaging (GCM)</strong>. GCM is the next generation of C2DM.</p>
<p>This document is addressed to C2DM developers who are moving to GCM. It describes the differences between GCM and C2DM, and explains how to migrate existing C2DM apps to GCM.</p>
<h2 id="history">Historical Overview</h2>
<p>C2DM was launched in 2010 to help Android apps send data from servers to their applications. Servers can tell apps to contact the server directly, to fetch updated application or user data. The C2DM service handles all aspects of queueing of messages and delivery to the target application running on the target device.</p>
<p>GCM replaces C2DM. The focus of GCM is as follows:</p>
<ul>
<li> Ease of use. No sign-up forms.</li>
<li>No quotas.</li>
<li>GCM and C2DM stats are available through the <a href="http://play.google.com/apps/publish">Android Developer Console</a>.</li>
<li>Battery efficiency.</li>
<li>Rich set of new APIs.</li>
</ul>
<h2 id="diffs">How is GCM Different from C2DM?</h2>
<p>GCM builds on the core foundation of C2DM. Here is what's different:</p>
<dl>
<dt><strong>Simple API Key</strong></dt>
<dd>To use the GCM service, you need to obtain a Simple API Key from Google APIs console page. For more information, see <a href="gs.html">Getting Started</a>. Note that GCM <em>only</em> accepts Simple API Key—using ClientLogin or OAuth2 tokens will not work.
</dd>
<dt><strong>Sender ID</strong></dt>
<dd>In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project ID that you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. </dd>
<dt><strong>JSON format</strong></dt>
<dd>GCM HTTP requests support JSON format in addition to plain text. For more information, see the <a href="gcm.html#send-msg">Architectural Overview</a>.</dd>
<dt><strong>Multicast messages</strong></dt>
<dd>In GCM you can send the same message to multiple devices simultaneously. For example, a sports app wanting to deliver a score update to fans can now send the message to up to 1000 registration IDs in the same request (requires JSON). For more information, see the <a href="gcm.html#send-msg">Architectural Overview</a>.</dd>
<dt><strong>Multiple senders</strong></dt>
<dd>Multiple parties can send messages to the same app with one common registration ID. For more information, see <a href="adv.html#multi-senders">Advanced Topics</a>.</dd>
<dt><strong>Time-to-live messages</strong></dt>
<dd>Apps like video chat and calendar apps can send expiring invitation events with a time-to-live value between 0 and 4 weeks. GCM will store the messages until they expire. A message with a time-to-live value of 0 will not be stored on the GCM server, nor will it be throttled. For more information, see <a href="adv.html#ttl">Advanced Topics</a>.</dd>
<dt><strong>Messages with payload</strong></dt>
<dd>Apps can use "messages with payload" to deliver messages of up to 4 Kb. This would be useful in a chat application, for example. To use this feature, simply omit the <code>collapse_key</code> parameter and messages will not be collapsed. GCM will store up to 100 messages. If you exceed that number, all messages will be discarded but you will receive a special message. If an application receives this message, it needs to sync with the server. For more information, see <a href="adv.html#collapsible">Advanced Topics</a>.</dd>
<dt><strong>Canonical registration ID</strong></dt>
<dd>There may be situations where the server ends up with 2 registration IDs for the same device. If the GCM response contains a registration ID, simply replace the registration ID you have with the one provided. With this feature your application doesn't need to send the device ID to your server anymore. For more information, see <a href="adv.html#canonical">Advanced Topics</a>.</dd>
</dl>
<p>GCM also provides helper libraries (<a href="{@docRoot}guide/google/gcm/client-javadoc/index.html">client</a> and <a href="{@docRoot}guide/google/gcm/server-javadoc/index.html">server</a>) to make writing your code easier.</p>
<h2 id="migrating">Migrating Your Apps</h2>
<p>This section describes how to move existing C2DM apps to GCM.</p>
<h3 id="client">Client changes</h3>
<p>Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project ID generated when signing up for the new service. For example:</p>
<pre class="prettyprint pretty-java">Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER");
// sets the app name in the intent
registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0));
registrationIntent.putExtra("sender", senderID);
startService(registrationIntent);</pre>
<p>After receiving a response from GCM, the registration ID obtained must be sent to the application server. When doing this, the application should indicate that it is sending a GCM registration ID so that the server can distinguish it from existing C2DM registrations.</p>
<h3 id="server">Server changes</h3>
<p>When the application server receives a GCM registration ID, it should store it and mark it as such.</p>
<p>Sending messages to GCM devices requires a few changes:</p>
<ul>
<li> The request should be sent to a new endpoint: <code>https://android.googleapis.com/gcm/send</code>.</li>
<li>The Authorization header of the request should contain the API key generated during sign up. This key replaces the deprecated ClientLogin Auth token.</li>
</ul>
<p>For example:
</p>
<pre>Content-Type:application/json
Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA
{
"registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
"data" : {
"Team" : "Portugal",
"Score" : "3",
"Player" : "Varela",
},
}</pre>
<p>For a detailed discussion of this topic and more examples, see the <a href="gcm.html#send-msg">Architectural Overview</a>.</p>
<p>Eventually, once enough users of your application have migrated to the new service, you might want to take advantage of the new <a href="gcm.html#send-msg">JSON-formatted</a> requests that give access to the full set of features provided by GCM.</p>
|
