1 page.title=Migration 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>Quickview</h2> 8 9 <ul> 10 <li>Understand the differences between GCM and C2DM.</li> 11 <li>Learn how to migrate an app from C2DM to GCM.</li> 12 13 </ul> 14 15 16 <h2>In this document</h2> 17 18 <ol> 19 <li><a href="#history">Historical Overview</a></li> 20 <li><a href="#diffs">How is GCM Different from C2DM?</a> 21 <ol> 22 <li><a href="#interop">Relationship between C2DM and GCM</a></li> 23 </ol> 24 </li> 25 <li><a href="#migrating">Migrating Your Apps</a> 26 <ol> 27 <li><a href="#client">Client changes</a></li> 28 <li><a href="#server">Server changes</a></li> 29 </ol> 30 </li> 31 </ol> 32 33 </div> 34 </div> 35 36 <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> 37 <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> 38 39 40 <h2 id="history">Historical Overview</h2> 41 <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> 42 <p>GCM replaces C2DM. The focus of GCM is as follows:</p> 43 <ul> 44 <li> Ease of use. No sign-up forms.</li> 45 <li>No quotas.</li> 46 <li>GCM and C2DM stats are available through the <a href="http://play.google.com/apps/publish">Developer Console</a>.</li> 47 <li>Battery efficiency.</li> 48 <li>Rich set of new APIs.</li> 49 </ul> 50 <h2 id="diffs">How is GCM Different from C2DM?</h2> 51 <p>GCM builds on the core foundation of C2DM. Here is what's different:</p> 52 53 <dl> 54 <dt><strong>Simple API Key</strong></dt> 55 <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. 56 </dd> 57 <dt><strong>Sender ID</strong></dt> 58 <dd>In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project number that you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. </dd> 59 60 <dt><strong>JSON format</strong></dt> 61 <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> 62 63 <dt><strong>Multicast messages</strong></dt> 64 <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> 65 66 <dt><strong>Multiple senders</strong></dt> 67 <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> 68 69 <dt><strong>Time-to-live messages</strong></dt> 70 <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> 71 72 <dt><strong>Messages with payload</strong></dt> 73 <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> 74 75 <dt><strong>Canonical registration ID</strong></dt> 76 <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> 77 </dl> 78 <p>GCM also provides client and server <a href="{@docRoot}reference/com/google/android/gcm/package-summary.html">helper libraries</a> to make writing your code easier.</p> 79 80 <h3 id="interop">Relationship between C2DM and GCM</h3> 81 82 <p>C2DM and GCM are not interoperable. For example, you cannot post notifications from GCM to C2DM registration IDs, nor can you use C2DM registration IDs as GCM registration IDs. From your server-side application, you must keep keep track of whether a registration ID is from C2DM or GCM and use the proper endpoint. </p> 83 84 <p>As you transition from C2DM to GCM, your server needs to be aware of whether a given registration ID 85 contains an old C2DM sender or a new GCM project number. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.</p> 86 87 <h2 id="migrating">Migrating Your Apps</h2> 88 <p>This section describes how to move existing C2DM apps to GCM.</p> 89 <h3 id="client">Client changes</h3> 90 <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 number generated when signing up for the new service. For example:</p> 91 <pre class="prettyprint pretty-java">Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER"); 92 // sets the app name in the intent 93 registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0)); 94 registrationIntent.putExtra("sender", senderID); 95 startService(registrationIntent);</pre> 96 <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> 97 <h3 id="server">Server changes</h3> 98 <p>When the application server receives a GCM registration ID, it should store it and mark it as such.</p> 99 <p>Sending messages to GCM devices requires a few changes:</p> 100 <ul> 101 <li> The request should be sent to a new endpoint: <code>https://android.googleapis.com/gcm/send</code>.</li> 102 <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> 103 </ul> 104 <p>For example: 105 </p> 106 <pre>Content-Type:application/json 107 Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA 108 109 { 110 "registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...", 111 "data" : { 112 "Team" : "Portugal", 113 "Score" : "3", 114 "Player" : "Varela", 115 }, 116 }</pre> 117 <p>For a detailed discussion of this topic and more examples, see the <a href="gcm.html#send-msg">Architectural Overview</a>.</p> 118 <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> 119 120
