Quickview
- Understand how to set up the server side of a GCM app.
- Become familiar with the GCM server helper library.
In this document
See Also
This document gives examples of GCM server-side code for HTTP. For an example of an XMPP server (Cloud Connection Server), see Getting Started. Note that a full GCM implementation requires a client-side implementation, in addition to the server. For a complete working example that includes client and server-side code, see Getting Started.
Requirements
For the web server:
- Ant 1.8 (it might work with earlier versions, but it's not guaranteed).
- One of the following:
- A running web server compatible with Servlets API version 2.5, such as Tomcat 6 or Jetty, or
- Java App Engine SDK version 1.6 or later.
- A Google account registered to use GCM.
- The API key for that account.
For the Android application:
- Emulator (or device) running Android 2.2 with Google APIs.
- The Google API project number of the account registered to use GCM.
Setting Up GCM
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 Google API Console.
For instructions on how to set up GCM, see Getting Started.
Setting Up an HTTP Server
This section describes the different options for setting up an HTTP server.
Using a standard web server
To set up the server using a standard, servlet-compliant web server:
- From the open source site, download the following directories:
gcm-server
,samples/gcm-demo-server
, andsamples/gcm-demo-appengine
. - In a text editor, edit the
samples/gcm-demo-server/WebContent/WEB-INF/classes/api.key
and replace the existing text with the API key obtained above. - In a shell window, go to the
samples/gcm-demo-server
directory. - Generate the server's WAR file by running
ant war
: - Deploy the
dist/gcm-demo.war
to your running server. For instance, if you're using Jetty, copygcm-demo.war
to thewebapps
directory of the Jetty installation. - 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
http://192.168.1.10:8080/gcm-demo/home
, wheregcm-demo
is the application context and/home
is the path of the main servlet.
$ 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: dist/gcm-demo.war BUILD SUCCESSFUL Total time: 0 seconds
Note: You can get the IP by running ifconfig
on Linux or MacOS, or ipconfig
on Windows.
You server is now ready.
Using App Engine for Java
To set up the server using a standard App Engine for Java:
- Get the files from the open source site, as described above.
- In a text editor, edit
samples/gcm-demo-appengine/src/com/google/android/gcm/demo/server/ApiKeyInitializer.java
and replace the existing text with the API key obtained above.Note: 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
Datastore Viewer
to change it later. - In a shell window, go to the
samples/gcm-demo-appengine
directory. - Start the development App Engine server by
ant runserver
, using the-Dsdk.dir
to indicate the location of the App Engine SDK and-Dserver.host
to set your server's hostname or IP address: - 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
http://192.168.1.10:8080/home
, where/home
is the path of the main servlet.
$ 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
Note: You can get the IP by running ifconfig
on Linux or MacOS, or ipconfig
on Windows.
You server is now ready.