Google Cloud

Messaging
GCM - Architecture
Device/App GCM Server App Server
Register for Push Notification
Registration ID
Send Registration ID to App Server
Store Registration ID in database
IM-AS
Send Message (HTTP)
Send HTTP request with payload
HTTP Response
HTTP Response
Registration

Communicating with GCM Server
Google provides connection servers for HTTP and XMPP (CCS Cloud Connection Server)
Authentication with GCM is done with an API-Key. Included in the header of HTTP Post request.
Each message need to be identified uniquely with message id.
Google enqueues and stores the message in case the device is offline.



HTTP
Downstream only only cloud to device.
Send messages as HTTP Post requests body plain text or json message
Synchronous sender has to wait for the response for previous message before sending next message.
Target should be either:
registration_ids: to send to 1 or more devices (upto 1000). Both unicast and multicast messages are possible
notification_key: to send to multiple devices owned by single user
Field Description Mandatory?
registration_ids String array with the list of registration ids (min-1 and max-1000) Y (if notification_key is not supplied)
notification_key String that maps single user to multiple registration ids. Y (if registration_ids is not supplied)
collapse_key Arbitrary string. When set, it will send only the last message to client when many
messages exist when device is offline. GCM allows only 4 collapse keys to be used
per device.
N
data JSON object with key-value pairs. Key and values could be any strings. There is
no limit on the number of key/value pairs, though there is a limit on the total
size of the message (4kb).
N
delay_while_idle If included, indicates that the message should not be sent immediately if
the device is idle.
N
time_to_live How long (in seconds) the message should be kept on GCM storage if the
device is offline. Default is 4 weeks.
N
dry_run If included, allows developers to test their request without actually sending a
message.
N
XMPP (CCS)
Supports both Upstream (Device to Cloud) and Downstream (Cloud to Device).
Communication would be asynchronous
JSON messages encapsulated in XMPP messages
Does not support multicast messaging. The to field can contain a single registration id or notification
key.
Field Description Mandatory?
to To specify registration id or notification key Y
message_id Uniquely identifies a message Y
message_type Special status message N
collapse_key Arbitrary string. When set, it will send only the last message to client when many messages exist
when device is offline. GCM allows only 4 collapse keys to be used per device.
N
data JSON object with key-value pairs. Key and values could be any strings. There is no limit on the
number of key/value pairs, though there is a limit on the total size of the message (4kb).
N
delay_while_idle If included, indicates that the message should not be sent immediately if the device is idle. N
time_to_live How long (in seconds) the message should be kept on GCM storage if the device is offline.
Default is 4 weeks.
N
Message
Payload: Optional. If required, can supply using the data parameter.

Send-to-sync vs Message with
Payload
Send-to-Sync:
message contains collapse_key parameter.
Used only when the latest message is relevant.
GCM allows only 4 collapse keys per device

Message with Payload:
Every message would be delivered to device.
Maximum payload is 4kb
Payload is provided through data parameter as json object.
HTTP
URL: https://android.googleapis.com/gcm/send
Ports to open from Push Proxy to GCM: 5228, 5229, and 5230

Responses:
200 OK
400 - request could not be parsed as JSON, or it contained invalid fields. Only for JSON requests.
401 - error authenticating the sender account.
5xx Internal Server error in GCM.



A canonical registration ID is defined to be the ID of the last registration requested by your application.
This is the ID that the server should use when sending messages to the device.
If later on you try to send a message using a different registration ID, GCM will process the request as
usual, but it will include the canonical registration ID in the registration_id field of the response. Make
sure to replace the registration ID stored in your server with this canonical ID, as eventually the ID
you're using will stop working.

Parsing of Response
Field Description
multicast_id Unique ID (number) identifying the multicast message.
success Number of messages that were processed without an error.
failure Number of messages that could not be processed.
canonical_ids Number of results that contain a canonical registration ID. See Advanced Topics for more discussion of this topic.
results Array of objects representing the status of the messages processed. The objects are listed in the same order as the request
(i.e., for each registration ID in the request, its result is listed in the same index in the response) and they can have these
fields:
message_id: String representing the message when it was successfully processed.
registration_id: If set, means that GCM processed the message but it has another canonical registration ID for that device,
so sender should replace the IDs on future requests (otherwise they might be rejected). This field is never set if there is an
error in the request.
error: String describing an error that occurred while processing the message for that recipient. The possible values are
the
same as documented in the above table, plus "Unavailable" (meaning GCM servers were busy and could not process the
message for that particular recipient, so it could be retried).