am 962b8f2b: am 14ba009a: am 6b4c3fed: docs: Refactor Google Services pages for site redesign

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>

  <ol>

    <li><a href="#interop">Relationship between C2DM and GCM</a></li>

  </ol>

</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) was officially deprecated on June 26, 2012, and will be

 shut down completely as of July 30, 2015.  <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">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&mdash;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 number 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 &quot;messages with payload&quot; 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>

<h3 id="interop">Relationship between C2DM and GCM</h3>

<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 track of whether a registration ID is from C2DM or GCM and use the proper endpoint. </p>

<p>As you transition from C2DM to GCM, your server needs to be aware of whether a given registration ID

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>

<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! Just re-register the client app for your target GCM-enabled platform. For

  example, see <a href="{@docRoot}google/gcm/client.html#sample-register">Register for GCM</a></p>

<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>

page.title=GCM Demo Application

@jd:body

<div id="deprecatedSticker">

  <a href="#" 

     onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false">

    <strong>This doc is deprecated</strong></a>

</div>

<div id="naMessage" style="display:block">

<div><p><strong>The information in this document has been superseded by <a href="server.html">GCM Server</a> and <a href="client.html">GCM Client</a></strong>. Please use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">{@code GoogleCloudMessaging}</a> API instead of the GCM client helper library. The GCM server helper library is still valid.</p>

 <input style="margin-top:1em;padding:5px" type="button"

        value="That's nice, but I still want to read this document"

onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" />

</div>

</div>

<div id="qv-wrapper">

<div id="qv">

<h2>Quickview</h2>

<ul>

<li>Build and run the GCM demo app.</li>

<li>Understand how to set up both the client and server sides of a GCM app.</li>

<li>Become familiar with the GCM helper libraries.</li>

</ul>

<h2>In this document</h2>

<ol>

  <li><a href="#requirements">Requirements</a> </li>

  <li><a href="#gcm-setup">Setting Up GCM</a></li>

  <li><a href="#server-setup">Setting Up the Server</a>

    <ol>

      <li><a href="#webserver-setup">Using a standard web server</a></li>

      <li><a href="#appengine-setup">Using App Engine for Java</a></li>

    </ol>

  </li>

  <li><a href="#device-setup">Setting Up the Device</a></li>

</ol>

</div>

</div>

<p class="note"><strong>Note:</strong> This tutorial describes how to develop GCM-enabled apps using the helper libraries. This is just one approach. For a more comprehensive discussion of the available APIs and development paths, see <a href="gs.html">Getting Started</a>.

<p>The Google Cloud Messaging (GCM) Demo demonstrates how to use the Google Cloud Messaging framework in your Android application. This tutorial walks you through setting up and running the demo.</p>

<p>This demo consists of the following pieces: </p>

<ul>

  <li>A web server containing a page where you can send messages.</li>

  <li>An Android application that receives and displays such messages.</li>

</ul>

<p>See the <a href="{@docRoot}reference/com/google/android/gcm/package-summary.html">reference</a> for the client and server helper libraries used in this demo.</p>

<p>The sections below describe how to download the demo code and helper libraries from the SDK Manager. The demo code and helper libraries are also available at the <a href="http://code.google.com/p/gcm">open source site</a>.

<h2 id="requirements">Requirements</h2>

<p>For the web server:</p>

<ul>

  <li> <a href="http://ant.apache.org/">Ant 1.8</a> (it might work with earlier versions, but it's not guaranteed).</li>

  <li>One of the following:

    <ul>

      <li>A running web server compatible with Servlets API version 2.5, such as <a href="http://tomcat.apache.org/">Tomcat 6</a> or <a href="http://jetty.codehaus.org/">Jetty</a>, or</li>

      <li><a href="http://code.google.com/appengine/">Java App Engine SDK</a> version 1.6 or later.</li>

    </ul>

  </li>

  <li>A Google account registered to use GCM.</li>

  <li>The API  key for that account.</li>

</ul>

<p>For the Android application:</p>

<ul>

  <li>Emulator (or device) running Android 2.2 with Google APIs.</li>

  <li>The Google API project number of the account registered to use GCM.</li>

</ul>

<h2 id="gcm-setup">Setting Up GCM</h2>

<p>Before proceeding with the server and client setup, it's necessary to register a Google account with the Google API Console, enable Google Cloud Messaging in GCM, and obtain an API key from the <a href="https://code.google.com/apis/console">Google API Console</a>.</p>

<p>For instructions on how to set up GCM, see <a href="gs.html">Getting Started</a>.</p>

<h2 id="server-setup">Setting Up the Server</h2>

<p>This section describes the different options for setting up a server.</p>

<h3 id="webserver-setup">Using a standard web server</h3>

<p>To set up the server using a standard, servlet-compliant web server:</p>

<ol>

  <li> From the SDK Manager, install <strong>Extras &gt; Google Cloud Messaging for Android Library</strong>.

    <p>This creates a <code>gcm</code> directory under <code><em>YOUR_SDK_ROOT</em>/extras/google/</code> containing these subdirectories: <code>gcm-client</code>, <code>gcm-server</code>, <code>samples/gcm-demo-client</code>, <code>samples/gcm-demo-server</code>, and <code>samples/gcm-demo-appengine</code>.</p>

<p class="note"><strong>Note:</strong> If you don't see <strong>Extras &gt; Google Cloud Messaging for Android Library</strong> in the SDK Manager, make sure you are running version 20 or higher. Be sure to restart the SDK Manager after updating it.</p>

  </li>

  <li>In a text editor, edit the <code>samples/gcm-demo-server/WebContent/WEB-INF/classes/api.key</code> and replace the existing text with the API key obtained above.</li>

  <li>In a shell window, go to the <code>samples/gcm-demo-server</code> directory.</li>

  <li>Generate the server's WAR file by running <code>ant war</code>:</li>

  <pre class="prettyprint">$ ant war

Buildfile:build.xml

init:

   [mkdir] Created dir: build/classes

   [mkdir] Created dir: dist

compile:

   [javac] Compiling 6 source files to build/classes

war:

     [war] Building war: <strong>dist/gcm-demo.war</strong>

BUILD SUCCESSFUL

Total time: 0 seconds

</pre>

  <li>Deploy the <code>dist/gcm-demo.war</code> to your running server. For instance, if you're using Jetty, copy <code>gcm-demo.war</code> to the <code>webapps</code> directory of the Jetty installation.</li>

  <li>Open the server's main page in a browser. The URL depends on the server you're using and your machine's IP address, but it will be something like <code>http://192.168.1.10:8080/gcm-demo/home</code>, where <code>gcm-demo</code> is the application context and <code>/home</code> is the path of the main servlet.

  </li>

</ol>

<p class="note"><strong>Note:</strong> You can get the IP by running <code>ifconfig</code> on Linux or MacOS, or <code>ipconfig</code> on Windows. </p>

<p> You server is now ready.</p>

<h3 id="appengine-setup">Using App Engine for Java</h3>

<p>To set up the server using a standard App Engine for Java:</p>

<ol>

  <li> From the SDK Manager, install <strong>Extras &gt; Google Cloud Messaging for Android Library</strong>.

    <p>This creates a <code>gcm</code> directory under <code><em>YOUR_SDK_ROOT</em>/extras/google/</code> containing these subdirectories: <code>gcm-client</code>, <code>gcm-server</code>, <code>samples/gcm-demo-client</code>, <code>samples/gcm-demo-server</code>, and <code>samples/gcm-demo-appengine</code>.</p>

  </li>

  <li>In a text editor, edit <code>samples/gcm-demo-appengine/src/com/google/android/gcm/demo/server/ApiKeyInitializer.java</code> and replace the existing text with the API key obtained above.

  <p class="note"><strong>Note:</strong> The API key value set in that class will be used just once to create a persistent entity on App Engine. If you deploy the application, you can use App Engine's <code>Datastore Viewer</code> to change it later.</p>

  </li>

  <li>In a shell window, go to the <code>samples/gcm-demo-appengine</code> directory.</li>

  <li>Start the development App Engine server by <code>ant runserver</code>, using the <code>-Dsdk.dir</code> to indicate the location of the App Engine SDK and <code>-Dserver.host</code> to set your server's hostname or IP address:</li>

<pre class="prettyprint">

$ ant -Dsdk.dir=/opt/google/appengine-java-sdk runserver -Dserver.host=192.168.1.10

Buildfile: gcm-demo-appengine/build.xml

init:

    [mkdir] Created dir: gcm-demo-appengine/dist

copyjars:

compile:

datanucleusenhance:

  [enhance] DataNucleus Enhancer (version 1.1.4) : Enhancement of classes

  [enhance] DataNucleus Enhancer completed with success for 0 classes. Timings : input=28 ms, enhance=0 ms, total=28 ms. Consult the log for full details

  [enhance] DataNucleus Enhancer completed and no classes were enhanced. Consult the log for full details

runserver:

     [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.jetty.JettyLogger info

     [java] INFO: Logging to JettyLogger(null) via com.google.apphosting.utils.jetty.JettyLogger

     [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AppEngineWebXmlReader readAppEngineWebXml

     [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/appengine-web.xml

     [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AbstractConfigXmlReader readConfigXml

     [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/web.xml

     [java] Jun 15, 2012 8:46:09 PM com.google.android.gcm.demo.server.ApiKeyInitializer contextInitialized

     [java] SEVERE: Created fake key. Please go to App Engine admin console, change its value to your API Key (the entity type is 'Settings' and its field to be changed is 'ApiKey'), then restart the server!

     [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start

     [java] INFO: The server is running at http://192.168.1.10:8080/

     [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start

     [java] INFO: The admin console is running at http://192.168.1.10:8080/_ah/admin

</pre>

  <li>Open the server's main page in a browser. The URL depends on the server you're using and your machine's IP address, but it will be something like <code>http://192.168.1.10:8080/home</code>, where <code>/home</code> is the path of the main servlet.</li>

  <p class="note"><strong>Note:</strong> You can get the IP by running <code>ifconfig</code> on Linux or MacOS, or <code>ipconfig</code> on Windows.</p>

</ol>

<p> You server is now ready.</p>

<h2 id="device-setup">Setting Up the Device</h2>

<p>To set up the device:</p>

<ol>

  <li> From the SDK Manager, install <strong>Extras &gt; Google Cloud Messaging for Android Library</strong>.

    <p>This creates a <code>gcm</code> directory under <code><em>YOUR_SDK_ROOT</em>/extras/google</code> containing these subdirectories: <code>gcm-client</code>, <code>gcm-server</code>, <code>samples/gcm-demo-client</code>, <code>samples/gcm-demo-server</code>, and <code>samples/gcm-demo-appengine</code>.</p>

  </li>

  <li>Using a text editor, open  <code>samples/gcm-demo-client/src/com/google/android/gcm/demo/app/CommonUtilities.java</code> and set the proper values for the <code>SENDER_ID</code> and <code>SERVER_URL</code> constants. For example:</li>

<pre class="prettyprint pretty-java">

static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo";

static final String SENDER_ID = &quot;4815162342&quot;;</pre>

<p>Note that the <code>SERVER_URL</code> is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (<code>/</code>). Also note that <code>SENDER_ID</code> is the Google API project number you obtained in the server setup steps above.</p>

  <li>In a shell window, go to the <code>gcm-demo-client</code> directory.</li>

  <li>Use the SDK's <code>android</code> tool to generate the <code>ant</code> build files:</li>

<pre class="prettyprint">

$ android update project --name GCMDemo -p . --target android-16

Updated project.properties

Updated local.properties

Updated file ./build.xml

Updated file ./proguard-project.txt

</pre>

<p>If this command fails becase <code>android-16</code> is not recognized, try a different target (as long as it is at least <code>android-15</code>).</p>

<li>Use <code>ant</code> to build the application's APK file:</li>

 <pre class="prettyprint">

$ ant clean debug

Buildfile: build.xml

...

-do-debug:

[zipalign] Running zip align on final apk...

    [echo] Debug Package: bin/GCMDemo-debug.apk

[propertyfile] Creating new property file: <strong>bin/build.prop</strong>

[propertyfile] Updating property file: bin/build.prop

[propertyfile] Updating property file: bin/build.prop

[propertyfile] Updating property file: bin/build.prop

-post-build:

debug:

BUILD SUCCESSFUL

Total time: 3 seconds

 </pre>

<li>Start the Android emulator:</li>

<pre class="prettyprint">$emulator -avd my_avd

</pre>

<p> This example assumes there is an AVD (Android Virtual Device) named <code>my_avd</code> previously configured with Android 2.2 and Google APIs level 8. For more information on how to run an Android emulator, see <a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a> in the Android Developers Guide.</p>

<li>Make sure there is a Google account added to the emulator. It doesn't have to be any account (like the <code>senderId</code>) in particular. </li>

<p> If the emulator is running Android 4.0.4 or later, this step is optional as GCM does not require an account from this version on.</p>

<li>Install the application in the emulator:</li>

<pre class="prettyprint">

$ ant installd

Buildfile: gcm-demo-client/build.xml

-set-mode-check:

-set-debug-files:

install:

     [echo] Installing gcm-demo-client/bin/GCMDemo-debug.apk onto default emulator or device...

     [exec] 1719 KB/s (47158 bytes in 0.026s)

     [exec]   pkg: /data/local/tmp/GCMDemo-debug.apk

     [exec] Success

installd:

BUILD SUCCESSFUL

Total time: 3 seconds

</pre>

  <li>In the emulator, launch the GCM Demo app. The initial screen should look like this:</li>

  <p><img src="{@docRoot}images/gcm/gcm-avd-home-auto-reg.png" class="screenshot" /></p>

<p class="note"><strong>Note:</strong> What happened? When the device received a registration callback intent from GCM, it contacted the server to register itself, using the register servlet and passing the registration ID received from GCM; the server then saved the registration ID to use it to send messages to the phone.</p>

<li> Now go back to your browser and refresh the page. It will show that there is one device registered:</li>

<p><img src="{@docRoot}images/gcm/gcm-device-reg.png" class="screenshot" /></p>

<li>Click on <strong>Send Message</strong>. The browser should show:</li>

<p><img src="{@docRoot}images/gcm/gcm-sent-server.png" class="screenshot" /></p>

<p>And in your emulator:</p>

<p><img src="{@docRoot}images/gcm/gcm-avd-first-msg.png" class="screenshot" /></p>

<p class="note"><strong>Note:</strong> What happened? When you clicked the button, the web server sent a message to GCM addressed to your device (more specifically, to the registration ID returned by GCM during the registration step). The device then received the message and displayed in the main activity; it also issued a system notification so the user would be notified even if the demo application was not running.</p>

</ol>