GCM HTTP Connection Server

This document describes the Google Cloud Messaging (GCM) HTTP connection server. Connection servers are the Google-provided servers that take messages from the 3rd-party application server and sending them to the device.

Note: The content in this document applies to GCM with Chrome apps as well as Android.

See the Server Reference for a list of all the message parameters and which connection server(s) supports them.

Authentication

To send a message, the application server issues a POST request. For example:

https://android.googleapis.com/gcm/send

A message request is made of 2 parts: HTTP header and HTTP body.

The HTTP header must contain the following headers:

  • Authorization: key=YOUR_API_KEY
  • Content-Type: application/json for JSON; application/x-www-form-urlencoded;charset=UTF-8 for plain text. If Content-Type is omitted, the format is assumed to be plain text.

For example:

Content-Type:application/json
Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA

{
  "registration_ids" : ["APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx..."],
  "data" : {
    ...
  },
}

The HTTP body content depends on whether you're using JSON or plain text. See the Server Reference for a list of all the parameters your JSON or plain text message can contain.

Checking the validity of an API key

If you receive authentication errors when sending messages, check the validity of your API key. For example, on Android, run the following command:

# api_key=YOUR_API_KEY

# curl --header "Authorization: key=$api_key" \
       --header Content-Type:"application/json" \
       https://android.googleapis.com/gcm/send \
       -d "{\"registration_ids\":[\"ABC\"]}"

If you receive a 401 HTTP status code, your API key is not valid. Otherwise you should see something like this:

{"multicast_id":6782339717028231855,"success":0,"failure":1,
"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}

If you want to confirm the validity of a registration ID, you can do so by replacing "ABC" with the registration ID.

Request Format

This section shows you how to format a request for both JSON and plain text. See the Server Reference for a complete list of the fields you can include in a request.

Here is the smallest possible request (a message without any parameters and just one recipient) using JSON:

{ "registration_ids": [ "42" ] }

And here the same example using plain text:

registration_id=42

Here is a message with a payload and 6 recipients:

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "registration_ids": ["4", "8", "15", "16", "23", "42"]
}

Here is a message with all optional fields set and 6 recipients:

{ "collapse_key": "score_update",
  "time_to_live": 108,
  "delay_while_idle": true,
  "data": {
    "score": "4x8",
    "time": "15:16.2342"
  },
  "registration_ids":["4", "8", "15", "16", "23", "42"]
}

And here is the same message using plain-text format (but just 1 recipient):

collapse_key=score_update&time_to_live=108&delay_while_idle=1&data.score=4x8&data.time=15:16.2342&registration_id=42
  

Here is a message that includes a notification key and payload:

{
  "data": {
    "message": "ciao"
  },
  "notification_key":"aUniqueKey"
}

For more information about notifications and how to use them, see User Notifications.

Note: If your organization has a firewall that restricts the traffic to or from the Internet, you need to configure it to allow connectivity with GCM in order for your GCM client apps to receive messages. The ports to open are: 5228, 5229, and 5230. GCM typically only uses 5228, but it sometimes uses 5229 and 5230. GCM doesn't provide specific IPs, so you should allow your firewall to accept outgoing connections to all IP addresses contained in the IP blocks listed in Google's ASN of 15169.

Response format

There are two possible outcomes when trying to send a message:

  • The message is processed successfully. The HTTP response has a 200 status, and the body contains more information about the status of the message (including possible errors).
  • The GCM server rejects the request. The HTTP response contains a non-200 status code (such as 400, 401 or 5xx).

When a JSON request is successful (HTTP status code 200), the JSON object returned contains the Downstream HTTP message response body.

If the value of failure and canonical_ids is 0, it's not necessary to parse the remainder of the response. Otherwise, we recommend that you iterate through the results field and do the following for each object in that list:

  • If message_id is set, check for registration_id:
    • If registration_id is set, replace the original ID with the new value (canonical ID) in your server database. Note that the original ID is not part of the result, so you need to obtain it from the list of code>registration_ids passed in the request (using the same index).
  • Otherwise, get the value of error:
    • If it is Unavailable, you could retry to send it in another request.
    • If it is NotRegistered, you should remove the registration ID from your server database because the application was uninstalled from the device, or the client app isn't configured to receive messages.
    • Otherwise, there is something wrong in the registration ID passed in the request; it is probably a non-recoverable error that will also require removing the registration from the server database. See Downstream message error response codes for all possible error values.

When a plain-text request is successful (HTTP status code 200), the response body contains 1 or 2 lines in the form of key/value pairs. The first line is always available and its content is either id=ID of sent message or Error=GCM error code. The second line, if available, has the format of registration_id=canonical ID. The second line is optional, and it can only be sent if the first line is not an error. We recommend handling the plain-text response in a similar way as handling the JSON response:

  • If first line starts with id, check second line:
    • If second line starts with registration_id, gets its value and replace the registration IDs in your server database.
  • Otherwise, get the value of Error:
    • If it is NotRegistered, remove the registration ID from your server database.
    • Otherwise, there is probably a non-recoverable error (Note: Plain-text requests will never return Unavailable as the error code, they would have returned a 500 HTTP status instead).

Example responses

This section shows a few examples of responses indicating messages that were processed successfully. See Request Format for the requests these responses are based on.

Here is a simple case of a JSON message successfully sent to one recipient without canonical IDs in the response:

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "canonical_ids": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

Or if the request was in plain-text format:

id=1:08

Here are JSON results for 6 recipients (IDs 4, 8, 15, 16, 23, and 42 respectively) with 3 messages successfully processed, 1 canonical registration ID returned, and 3 errors:

{ "multicast_id": 216,
  "success": 3,
  "failure": 3,
  "canonical_ids": 1,
  "results": [
    { "message_id": "1:0408" },
    { "error": "Unavailable" },
    { "error": "InvalidRegistration" },
    { "message_id": "1:1516" },
    { "message_id": "1:2342", "registration_id": "32" },
    { "error": "NotRegistered"}
  ]
}

In this example:

  • First message: success, not required.
  • Second message: should be resent (to registration ID 8).
  • Third message: had an unrecoverable error (maybe the value got corrupted in the database).
  • Fourth message: success, nothing required.
  • Fifth message: success, but the registration ID should be updated in the server database (from 23 to 32).
  • Sixth message: registration ID (42) should be removed from the server database because the application was uninstalled from the device.

Or if just the 4th message above was sent using plain-text format:

Error=InvalidRegistration

If the 5th message above was also sent using plain-text format:

id=1:2342
registration_id=32

Implementing an HTTP-Based App Server

This section gives examples of implementing an app server that works with the GCM HTTP connection server. Note that a full GCM implementation requires a client-side implementation, in addition to the server. This example is based on Android.

Requirements

For the web server:

  • Ant 1.8 (it might work with earlier versions, but it's not guaranteed).
  • One of the following:
  • A Google account registered to use GCM.
  • The API key for that account.

For the Android application:

  • Emulator (or device) running Android 2.2 (ideally, 2.3 or above) 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:

  1. From the open source site, download the following directories: gcm-server, samples/gcm-demo-server, and samples/gcm-demo-appengine.

  2. 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.
  3. In a shell window, go to the samples/gcm-demo-server directory.
  4. Generate the server's WAR file by running ant war:
  5. $ 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
    
  6. Deploy the dist/gcm-demo.war to your running server. For instance, if you're using Jetty, copy gcm-demo.war to the webapps directory of the Jetty installation.
  7. 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, where gcm-demo is the application context and /home is the path of the main servlet.

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:

  1. Get the files from the open source site, as described above.

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

  3. In a shell window, go to the samples/gcm-demo-appengine directory.
  4. 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:
  5. $ 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
    
  6. 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.
  7. Note: You can get the IP by running ifconfig on Linux or MacOS, or ipconfig on Windows.

You server is now ready.