Bridging Via GCM

Bridging via Google Cloud Messaging

Intro

Google Cloud Messaging (GCM) is the native messaging system for Android mobile devices. Bridging is desired because it reduces the CPU and battery demand to provide a continuous connection to remote devices. Autopush can take advantage of the GCM bridge by routing events over GCM for receipt by the client.

Configuration

Please see How to set up your GCM account for instructions about configuration and use of GCM. Note, this document will only briefly discuss GCM use and configuration.

GCM requires that both the recipient client know the SENDERID. The SENDERID is the Project ID for your android application, and is available on the Google Developer Console page as the "Project Number" for your application (e.g. "1234567890123"). The SENDERID is used

On the server, you will need to specify a valid Auth Credential Key for the account owning the SENDERID project. This is available under APIs & Auth >> Credentials. Generate a new value and store as gcm_apikey in the .autopush_endpoint configuration file. NOTE: This value is sensitive and should be protected from disclosure.

Use

The first thing that's required on the client is to register a GCM RegistrationID by calling String regid = com.google.android.gms.gcm.GoogleCloudMessaging.getInstance(Activity).register(SENDERID); (Note: the previous was for illustration only. Please consult the GCM documentation for the proper means of getting a Registration ID)

Once you have the registration ID, the client needs to register it with the Push server using the Push registration REST API.

POST https://updates.push.services.mozilla.org/register with a JSON body of:

{ "type": "gcm",
  "data": {
      "token": _regid_, /* _regid_ == the value returned from the above ...register() call */
  }
 }

If this is NOT the first time you are registering a UAID, be sure to call POST https://updates.push.services.mozilla.org/register/_uaid_ (where _uaid_ is the 'uaid' value returned in the body of the initial /register call) with a Authorization: header set to the secret and the same arguments for the body. This will create a new channel rather than generate a new UAID/ChannelID pair.

The response contains the endpoint to send to the App Server, the secret for hash token for subsequent command calls, and the uaid and channelID pair which uniquely identifies the User Agent Identifier which designates the end device, and the Push Channel Identifier, which identifies the discrete channel that will carry message data.

Please note, it is up to the client to note if the GCM RegistrationID has changed since it was last registered. If it has, the Client App must update it on the server by calling PUT https://updates.push.services.mozilla.org/register/_uaid_ (where _uaid_ is the UAID returned by the initial /register call) with a JSON body of:

{"type": "gcm",
 "data": { "token": _newRegid_, } /* where _newRegid_ == the new registration ID */
}

This will not require re-registration of the push endpoints, the server will simply update the GCM call back value.