Development‎ > ‎Tutorials‎ > ‎

Cloud to Device Messaging

Cloud to Device Messaging can be used so your app receives messages without polling. 
This saves battery power, it also minimizes data traffic and server load.
When a server app has a message for a specific client it connects to Google's server which then passes the message to the client.
The maximum size of the message is 1 kilobyte so the message should only contain information about where the client can download the data referred to by the message.

Client Registration

To receive messages, a client app needs to first obtain a registration ID by starting a service with the following kind of intent:
  • name=app value=a broadcast pending intent
  • name=sender value=the server account you signed up for
Once the service has obtained the registration id it will call back to a Receiver which has, in its intent filter, specified as the action and the apps package name as the category.
This receiver requires the permission.
This receiver can be specified in the manifest.xml or dynamically from your app's code using registerReceiver

The registration ID will be passed into the receiver in the registration_id  extra of the intent that started the receiver.
Send this ID to your server and store it there.

In order for an app to register to c2dm (and later to receive messages), the manifest must request these permissions:
  • android.permission.INTERNET obviously the message will be delivered through the internet 
  • yourAppsPackageName.permission.C2D_MESSAGE which you need to both set as uses-permission and create. Use the protectionLevel=signature parameter when creating the permission.
To unregister use the same intent but specify the action.

Server Registration

Sign up here.
Before you can send messages, you need to authorize your server with Google's server as described in Authentication and Authorization for Google APIs
This will result in an auth token which is required when sending the actual messages.

To get the auth token manually use this command
curl -d Email=theServerAccountYouSignedUpFor -d Passwd=yourPassword -d service=ac2dm
Which should return a key named Auth

Whenever your server wants to send a message, this token should be included in the request.

Sending Messages

To send a message, your server should make an HTTP post request to with these parameters:
  • registration_id identifies the client to which the message should be delivered
  • delay_while_idle (no value) keep the message waiting if the device is offline
  • collapse_key if a device is offline when sending the message, you might want to avoid overloading it with waiting messages when it comes online. Specify a value which you can reuse in the future when you want to replace existing messages.
  • data.<key> replace key by the name of your message. Your message can include several of these.
The request should also include this header:
Authorization: GoogleLogin auth=TheAuthTokenYouGotWhenRegistering

To send a message manually use this command
curl --header "Authorization: GoogleLogin auth=YourToken" "" -d registration_id=YourRegistrationId -d "data.message=YourMessage" -d collapse_key=YourCollapseKey -k

Receiving Messages

For your app to receive the message, you need to define another Receiver and specify the permission.
Its intent filter should have the action and the category set to your apps package name.
It should specify the permission as well.

The intent which started the receiver's onReceive method will have a number of extras with the names which the server specified in the data.<key> parameters. The values of these extras is your message which can then be handled any way your app wants.

More information:
Google Projects for Android: C2DM