1page.title=GCM Demo Application 2@jd:body 3 4<div id="deprecatedSticker"> 5 <a href="#" 6 onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> 7 <strong>This doc is deprecated</strong></a> 8</div> 9 10 11<div id="naMessage" style="display:block"> 12<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> 13 14 <input style="margin-top:1em;padding:5px" type="button" 15 value="That's nice, but I still want to read this document" 16onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> 17</div> 18</div> 19 20<div id="qv-wrapper"> 21<div id="qv"> 22 23<h2>Quickview</h2> 24 25<ul> 26<li>Build and run the GCM demo app.</li> 27<li>Understand how to set up both the client and server sides of a GCM app.</li> 28<li>Become familiar with the GCM helper libraries.</li> 29</ul> 30 31 32<h2>In this document</h2> 33 34<ol> 35 <li><a href="#requirements">Requirements</a> </li> 36 <li><a href="#gcm-setup">Setting Up GCM</a></li> 37 <li><a href="#server-setup">Setting Up the Server</a> 38 <ol> 39 <li><a href="#webserver-setup">Using a standard web server</a></li> 40 <li><a href="#appengine-setup">Using App Engine for Java</a></li> 41 </ol> 42 </li> 43 <li><a href="#device-setup">Setting Up the Device</a></li> 44</ol> 45 46</div> 47</div> 48 49<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>. 50 51<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> 52 53 54<p>This demo consists of the following pieces: </p> 55<ul> 56 <li>A web server containing a page where you can send messages.</li> 57 <li>An Android application that receives and displays such messages.</li> 58</ul> 59<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> 60 61<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>. 62 63<h2 id="requirements">Requirements</h2> 64<p>For the web server:</p> 65<ul> 66 <li> <a href="http://ant.apache.org/">Ant 1.8</a> (it might work with earlier versions, but it's not guaranteed).</li> 67 <li>One of the following: 68 <ul> 69 <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> 70 <li><a href="http://code.google.com/appengine/">Java App Engine SDK</a> version 1.6 or later.</li> 71 </ul> 72 </li> 73 <li>A Google account registered to use GCM.</li> 74 <li>The API key for that account.</li> 75</ul> 76<p>For the Android application:</p> 77<ul> 78 <li>Emulator (or device) running Android 2.2 with Google APIs.</li> 79 <li>The Google API project number of the account registered to use GCM.</li> 80</ul> 81<h2 id="gcm-setup">Setting Up GCM</h2> 82<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> 83<p>For instructions on how to set up GCM, see <a href="gs.html">Getting Started</a>.</p> 84 85 86<h2 id="server-setup">Setting Up the Server</h2> 87<p>This section describes the different options for setting up a server.</p> 88<h3 id="webserver-setup">Using a standard web server</h3> 89<p>To set up the server using a standard, servlet-compliant web server:</p> 90<ol> 91 <li> From the SDK Manager, install <strong>Extras > Google Cloud Messaging for Android Library</strong>. 92 93 94 <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> 95 96<p class="note"><strong>Note:</strong> If you don't see <strong>Extras > 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> 97 </li> 98 99 <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> 100 <li>In a shell window, go to the <code>samples/gcm-demo-server</code> directory.</li> 101 <li>Generate the server's WAR file by running <code>ant war</code>:</li> 102 103 <pre class="prettyprint">$ ant war 104 105Buildfile:build.xml 106 107init: 108 [mkdir] Created dir: build/classes 109 [mkdir] Created dir: dist 110 111compile: 112 [javac] Compiling 6 source files to build/classes 113 114war: 115 [war] Building war: <strong>dist/gcm-demo.war</strong> 116 117BUILD SUCCESSFUL 118Total time: 0 seconds 119</pre> 120 121 <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> 122 <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. 123 124 </li> 125</ol> 126<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> 127 128<p> You server is now ready.</p> 129<h3 id="appengine-setup">Using App Engine for Java</h3> 130 131<p>To set up the server using a standard App Engine for Java:</p> 132<ol> 133 <li> From the SDK Manager, install <strong>Extras > Google Cloud Messaging for Android Library</strong>. 134 <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> 135 </li> 136 <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. 137 <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> 138 139 </li> 140 <li>In a shell window, go to the <code>samples/gcm-demo-appengine</code> directory.</li> 141 <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> 142 143<pre class="prettyprint"> 144$ ant -Dsdk.dir=/opt/google/appengine-java-sdk runserver -Dserver.host=192.168.1.10 145Buildfile: gcm-demo-appengine/build.xml 146 147init: 148 [mkdir] Created dir: gcm-demo-appengine/dist 149 150copyjars: 151 152compile: 153 154datanucleusenhance: 155 [enhance] DataNucleus Enhancer (version 1.1.4) : Enhancement of classes 156 [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 157 [enhance] DataNucleus Enhancer completed and no classes were enhanced. Consult the log for full details 158 159runserver: 160 [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.jetty.JettyLogger info 161 [java] INFO: Logging to JettyLogger(null) via com.google.apphosting.utils.jetty.JettyLogger 162 [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AppEngineWebXmlReader readAppEngineWebXml 163 [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/appengine-web.xml 164 [java] Jun 15, 2012 8:46:06 PM com.google.apphosting.utils.config.AbstractConfigXmlReader readConfigXml 165 [java] INFO: Successfully processed gcm-demo-appengine/WebContent/WEB-INF/web.xml 166 [java] Jun 15, 2012 8:46:09 PM com.google.android.gcm.demo.server.ApiKeyInitializer contextInitialized 167 [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! 168 [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start 169 [java] INFO: The server is running at http://192.168.1.10:8080/ 170 [java] Jun 15, 2012 8:46:09 PM com.google.appengine.tools.development.DevAppServerImpl start 171 [java] INFO: The admin console is running at http://192.168.1.10:8080/_ah/admin 172</pre> 173 174 <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> 175 176 <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> 177 178</ol> 179<p> You server is now ready.</p> 180<h2 id="device-setup">Setting Up the Device</h2> 181<p>To set up the device:</p> 182<ol> 183 <li> From the SDK Manager, install <strong>Extras > Google Cloud Messaging for Android Library</strong>. 184 <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> 185 </li> 186 <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> 187 188<pre class="prettyprint pretty-java"> 189static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo"; 190static final String SENDER_ID = "4815162342";</pre> 191<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> 192 193 <li>In a shell window, go to the <code>gcm-demo-client</code> directory.</li> 194 <li>Use the SDK's <code>android</code> tool to generate the <code>ant</code> build files:</li> 195 196<pre class="prettyprint"> 197$ android update project --name GCMDemo -p . --target android-16 198Updated project.properties 199Updated local.properties 200Updated file ./build.xml 201Updated file ./proguard-project.txt 202</pre> 203<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> 204 205<li>Use <code>ant</code> to build the application's APK file:</li> 206 207 <pre class="prettyprint"> 208$ ant clean debug 209Buildfile: build.xml 210 211... 212 213 214-do-debug: 215[zipalign] Running zip align on final apk... 216 [echo] Debug Package: bin/GCMDemo-debug.apk 217[propertyfile] Creating new property file: <strong>bin/build.prop</strong> 218[propertyfile] Updating property file: bin/build.prop 219[propertyfile] Updating property file: bin/build.prop 220[propertyfile] Updating property file: bin/build.prop 221 222-post-build: 223 224debug: 225 226BUILD SUCCESSFUL 227Total time: 3 seconds 228 </pre> 229 230<li>Start the Android emulator:</li> 231<pre class="prettyprint">$emulator -avd my_avd 232</pre> 233 234<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> 235 236<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> 237 238<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> 239 240<li>Install the application in the emulator:</li> 241 242<pre class="prettyprint"> 243$ ant installd 244Buildfile: gcm-demo-client/build.xml 245 246-set-mode-check: 247 248-set-debug-files: 249 250install: 251 [echo] Installing gcm-demo-client/bin/GCMDemo-debug.apk onto default emulator or device... 252 [exec] 1719 KB/s (47158 bytes in 0.026s) 253 [exec] pkg: /data/local/tmp/GCMDemo-debug.apk 254 [exec] Success 255 256installd: 257 258BUILD SUCCESSFUL 259Total time: 3 seconds 260</pre> 261 <li>In the emulator, launch the GCM Demo app. The initial screen should look like this:</li> 262 <p><img src="{@docRoot}images/gcm/gcm-avd-home-auto-reg.png" class="screenshot" /></p> 263<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> 264<li> Now go back to your browser and refresh the page. It will show that there is one device registered:</li> 265 266<p><img src="{@docRoot}images/gcm/gcm-device-reg.png" class="screenshot" /></p> 267 268<li>Click on <strong>Send Message</strong>. The browser should show:</li> 269<p><img src="{@docRoot}images/gcm/gcm-sent-server.png" class="screenshot" /></p> 270 271<p>And in your emulator:</p> 272 273<p><img src="{@docRoot}images/gcm/gcm-avd-first-msg.png" class="screenshot" /></p> 274 275<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> 276</ol> 277 278
