Android Cloud to Device Messaging Framework

Android Cloud to Device Messaging (C2DM) is  a   service that helps developers  send data from servers to their applications on  Android devices. The  service provides a simple, lightweight mechanism that servers can use  to tell mobile applications to contact the server directly, to fetch  updated application or user data. The C2DM service handles all aspects  of queueing of messages and delivery to the target application running  on the target device.


Here are the primary characteristics of Android Cloud to Device  Messaging (C2DM):

  • It allows third-party application servers to send lightweight messages to their Android applications. The messaging service is not designed for sending a lot of user content via the messages. Rather, it should be used to tell the application that there is new data on the server, so that the application can fetch it.
  • C2DM makes no guarantees about delivery or the order of messages. So, for example, while you might use this feature to tell an instant messaging application that the user has new messages, you probably would not use it to pass the actual messages.
  • An application on an Android device doesn’t need to be running to receive messages. The system will wake up the application via Intent broadcast when the the  message arrives, as long as the application is set up with the proper broadcast receiver and permissions.
  • It does not provide any  built-in user interface or other handling for message data. C2DM  simply passes raw message data received straight to the application,  which has full control of how to handle it. For example, the application might post a notification, display a custom user interface, or  silently sync data.
  • It requires devices running Android 2.2 or higher that also have the Market application installed. However, you are not limited to deploying your applications through Market.
  • It uses an existing connection for Google services. This requires users to set up their Google account on their mobile devices.

Architectural Overview

This section gives an overview of how C2DM works.

This table summarizes the key terms and concepts involved in C2DM. It is divided into these categories:

  • Components — The physical entities that play a role in C2DM.
  • Credentials — The IDs and tokens that are used in different stages of C2DM to ensure that all parties have been authenticated, and that the message is going to the correct place.
Mobile Device The device that is running an Android application that uses C2DM. This must be a 2.2 Android device that has Market installed, and it must have at least one logged in Google account.
Third-Party Application Server An application server that  developers  set up as part of implementing C2DM in their applications. The third-party application server sends data to an Android application on the device via the C2DM server.
C2DM Servers The Google servers involved in taking messages from the third-party application server and sending them to the device.
Sender ID An email account associated with the application’s developer. The sender ID is used in the registration process to identify a Android application that is permitted to send messages to the device. This ID is typically role-based rather than being a personal account—- for example,
Application ID The application that is registering to receive messages. The application is identified by the package name from the manifest. This  ensures that the messages are targeted to the correct application.
Registration ID An ID issued by the C2DM servers to the Android application that allows it to receive messages. Once the application has the registration ID, it sends it to the third-party application server, which uses it to identify each device  that has registered to receive messages for a given application. In other words, a registration ID is tied to a particular application running on a particular device.
Google User Account For C2DM to work, the mobile device must include at least one logged in Google account.
Sender Auth Token A ClientLogin Auth token that is saved on the third-party application server that gives the application server authorized access to Google services. The token is included in the header of POST requests  that send messages. For more discussion of ClientLogin Auth tokens, see ClientLogin for Installed Applications.

Lifecycle Flow

Here are the primary processes involved in cloud-to-device messaging:

  • Enabling C2DM. An Android application running on a mobile device registers to receive messages.
  • Sending a message. A third-party application server sends messages to the device.
  • Receiving a message. An Android application receives a message from a C2DM server.

These processes are described in more detail below.

Enabling C2DM

This is the sequence of events that occurs when an Android application running on a mobile device registers to receive messages:

  1. The first time the application needs to use the messaging service, it fires off a registration Intent to a C2DM server.This registration Intent (  includes the sender ID (that is, the account authorized to send messages to the  application, which is typically the email address of an account set up by the  application’s developer), and the application ID.
  2. If the registration is successful, the C2DM server broadcasts aREGISTRATIONIntent which gives the application  a registration ID.The application should store this ID for later use. Note that Google may periodically refresh the registration ID, so you should design your application with the understanding that the REGISTRATION Intent may be called multiple times. Your application needs to be able to respond accordingly.
  3. To complete the registration, the application sends the registration ID to the application server. The application server typically stores the registration ID in a database.

The registration ID lasts until the application explicitly unregisters itself, or until Google refreshes the registration ID for your application.

Sending a Message

For an application server to send a  message, the following things must be in place:

  • The application has a registration ID that allows it to receive messages for a particular device.
  • The third-party application server has stored the registration ID.

There is one more thing that needs to be in place for the application server to send messages:  a ClientLogin authorization token. This is something that the developer must have already set up on the application server for the application (for more discussion, seeRole of the Third-Party Application Server). Now it will get used to send messages to the device.

The ClientLogin token authorizes the application server to send messages to a particular Android application. An application server has one ClientLogin token for a particular 3rd party app, and multiple registration IDs. Each registration ID represents a particular device that has registered to use the messaging service for a particular 3rd party app.

Here is the sequence of events that occurs when the application server sends a  message:

  1. The application server sends a  message to  C2DM servers.
  2. Google enqueues and stores the message in case the device is inactive.
  3. When the device is online, Google sends the message to the device.
  4. On the device, the system  broadcasts the  message to the specified application via Intent broadcast with proper permissions, so that only the targeted application gets the message. This wakes the application up. The application does not need to be running beforehand to receive the message.
  5. The application processes the message. If the application is doing non-trivial processing, you may want to grab a wake lock and do any processing in a Service.

An application can  unregister C2DM if it no longer wants to receive  messages.

Receiving a Message

This is the sequence of events that occurs when an Android application running on a mobile device receives a message:

  1. The system receives the incoming message and extracts the raw key/value pairs from the message payload.
  2. The system passes the key/value pairs to the targeted Android application in a Intent as a set of extras.
  3. The Android application extracts the raw data from the RECEIVE Intent by key and processes the data.

What Does the User See?

When mobile device users install an applications that include C2DM, they will get a permission from Android Market informing them that the application includes C2DM. They must approve the use of this feature to install the application. Depending on the implementation of the application, it may offer users the option of unregistering to receive messages. Uninstalling the application also has the effect of unregistering.

Writing Android Applications that Use C2DM

To write Android applications that use C2DM, you must have an application server that can perform the tasks described in Role of the Third-Party Application Server. This section describes the steps you take to create a client application that uses C2DM.

Remember that there is no user interface associated with the C2DM Framework. However you choose to process messages in your application is up to you.

There are two primary steps involved in writing a client application:

  • Creating a manifest that contains the permissions the application needs to use C2DM.
  • Implementing your Java code. To use C2DM, this implementation must include:
    • Code to start and stop the registration service.
    • Receivers  for

Creating the Manifest

Every application must have an AndroidManifest.xml file (with precisely that   name) in its root directory.  The manifest presents essential information about   the application to the Android system, information the system must have before   it can run any of the application’s code (for more discussion of the manifest file, see the Android Developers Guide). To use the C2DM feature, the manifest must include the following:

  • states that the application has permission register and receive messages.
  • android.permission.INTERNET states that the application has permission to send the receiver key to the 3rd party server.
  • applicationPackage + ".permission.C2D_MESSAGE prevents other applications from registering and receiving the application’s messages.
  • Receivers for, with the category set as applicationPackage. The receiver should require permission, so that only the C2DM Framework can send it the message. Note that both registration and the receiving of messages are implemented as Intents.
  • If the C2DM feature is critical to the application’s function, be sure to set android:minSdkVersion="8" in the manifest. This ensures that the application cannot be installed in an environment in which it could not run properly.

Received C2D_MESSAGE Intents  have all key/value pairs sent by the 3rd party server as extras. One special key is collapse_key, which is specified by the sender to allow handling of messages waiting for an off-line device.

Here are excerpts from a manifest that supports C2DM:

<manifest package="com.example.myapp" ...>
   <!-- Only this application can receive the messages and registration result -->     <permission android:name="com.example.myapp.permission.C2D_MESSAGE" android:protectionLevel="signature" />    <uses-permission android:name="com.example.myapp.permission.C2D_MESSAGE" />
   <!-- This app has permission to register and receive message -->    <uses-permission android:name="" />
   <!-- Send the registration id to the server -->    <uses-permission android:name="android.permission.INTERNET" />
   <application...>       <!-- Only C2DM servers can send messages for the app. If permission is not set - any other app can generate it -->        <receiver android:name=".C2DMReceiver" android:permission="">           <!-- Receive the actual message -->           <intent-filter>               <action android:name="" />               <category android:name="com.example.myapp" />           </intent-filter>           <!-- Receive the registration id -->           <intent-filter>               <action android:name="" />               <category android:name="com.example.myapp" />           </intent-filter>       </receiver>       ...    </application>    ... </manifest>

Registering for C2DM

An Android application needs to register with  C2DM servers before receiving any message. To register it needs to send an Intent (, with 2 extra parameters:

  • sender is the ID of the account authorized to send messages to the application, typically the email address of an account set up by the application’s developer.
  • app is the application’s ID, set with a PendingIntent to allow the registration service to extract application information.

For example:

Intent registrationIntent = new Intent(""); registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0)); // boilerplate registrationIntent.putExtra("sender", emailOfSender); startService(registrationIntent);

Registration is not complete until the application sends the registration ID to the third-party application server. The application server  uses the registration ID to send messages that are targeted to the application running on that particular device.

Unregistering from C2DM

To unregister from C2DM:

Intent unregIntent = new Intent(""); unregIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0)); startService(unregIntent);

Handling Registration Results

As discussed in Creating the Manifest, the manifest defines a receiver for It also defines a receiver Note that both registration and the receiving of messages are implemented as Intents.

The main use of REGISTRATION is to allow the application to receive the registration  ID. The Intent can be sent at any time. Google may periodically refresh the receiver ID. An application receiving this Intent with a registration_id parameter must ensure that the third-party application server receives the registration ID. It may do so by saving the registration ID and sending it to the server. If the network is down or there are errors, the application should retry sending the registration ID  when the network is up again or the next time it starts. An application should keep track of its registration status and attempt to register again if the process is not fully completed.

The REGISTRATION Intent is generated with an errorparameter if the registration couldn’t be completed. If that happens, the application should try again later with exponential back off. When the application unregisters, the REGISTRATION Intent will be sent with an unregistered extra parameter.

Here are the possible error codes for the REGISTRATIONIntent:

Error Code Description
SERVICE_NOT_AVAILABLE The device can’t read the response, or there was a 500/503 from the server that can be retried later. The application should use exponential back off and retry.
ACCOUNT_MISSING There is no Google account on the phone.  The application should ask the user to open the account manager and add a Google account. Fix on the device side.
AUTHENTICATION_FAILED Bad password. The application should ask  the user to enter his/her password, and let user retry manually later. Fix on the device side.
TOO_MANY_REGISTRATIONS The user has too many applications registered.  The application should tell the user to uninstall some other applications, let user retry  manually. Fix on the device side.
INVALID_SENDER The sender account is not recognized.
PHONE_REGISTRATION_ERROR Incorrect phone registration with Google. This phone doesn’t currently support C2DM.

The application receives a REGISTRATION Intent broadcast whenever the application server attempts to send a message to it. But  registration IDs can be nonexistent or invalid for a variety of reasons:

  • If an application is running for the first time, it has no registration ID yet.
  • If the application unregistered, it has no registration ID.
  • The C2DM server periodically refreshes registration IDs.

An application must be prepared to handle every case. For example:

public void onReceive(Context context, Intent intent) {     if (intent.getAction().equals("")) {         handleRegistration(context, intent);     } else if (intent.getAction().equals("")) {         handleMessage(context, intent);      }  }
private void handleRegistration(Context context, Intent intent) {     String registration = intent.getStringExtra("registration_id");      if (intent.getStringExtra("error") != null) {         // Registration failed, should try again later.     } else if (intent.getStringExtra("unregistered") != null) {         // unregistration done, new messages from the authorized sender will be rejected     } else if (registration != null) {        // Send the registration ID to the 3rd party site that is sending the messages.        // This should be done in a separate thread.        // When done, remember that all registration is done.      } }

Handling Received Data

When the C2DM server receives a message from the third-party application server, C2DM extracts the raw key/value pairs from the message payload and passes them to the Android application in Intent as a set of extras. The application extracts the data by key and processes it, whatever that means for that application.

Here is an example:

protected void onReceive(Context context, Intent intent) {     String accountName = intent.getExtras().getString(Config.C2DM_ACCOUNT_EXTRA);     String message = intent.getExtras().getString(Config.C2DM_MESSAGE_EXTRA);     if (Config.C2DM_MESSAGE_SYNC.equals(message)) {         if (accountName != null) {             if (Log.isLoggable(TAG, Log.DEBUG)) {                 Log.d(TAG, "Messaging request received for account " + accountName);             }                          ContentResolver.requestSync(                 new Account(accountName, SyncAdapter.GOOGLE_ACCOUNT_TYPE),                 JumpNoteContract.AUTHORITY, new Bundle());         }     } }

Developing and Testing Your Applications

Here are some guidelines for developing and testing an Android application that uses the C2DM feature:

  • To develop and test your C2DM applications, you need to run and debug the applications on an Android 2.2 system image that includes the necessary underlying Google services.
  • To develop and debug on an actual device, you need a device running an Android 2.2 system image that includes the Market application.
  • To develop and test on the Android Emulator, you need to download the Android 2.2 version of the Google APIs Add-On into your SDK using the Android SDK and AVD Manager. Specifically, you need to download the component named “Google APIs by Google Inc, Android API 8”. Then, you need to set up an AVD that uses that system image.
  • If the C2DM feature is critical to the application’s function, be sure to set android:minSdkVersion="8" in the manifest. This ensures that the application cannot be installed in an environment in which it could not run properly.

Role of the Third-Party Application Server

Before you can write client applications that use the C2DM feature, you must have an HTTPS application server that meets the following criteria:

  • Able to communicate with your client.
  • Able to  fire off HTTP requests to the C2DM server.
  • Able to handle requests and queue data as needed. For example, it should be able to perform exponential back off.
  • Able to store the ClientLogin Auth token and client registration IDs. The ClientLogin Auth token  is included in the header of POST requests that send messages. For more discussion of this topic, see ClientLogin for Installed Applications. The server should store the token and have a policy to refresh it periodically.

How the Application Server Sends Messages

This section describes how the third-party application server sends messages to a 3rd party client application running on a mobile device.

Before the third-party application server can send a  message to an application, it must have received a registration ID from it.

To send a  message, the application server issues a POST request to that includes the following:

Field Description
registration_id The registration ID retrieved from the Android application on the phone. Required.
collapse_key An arbitrary string that is used to collapse a group of like messages when the device is offline, so that only the last message gets sent to the client. This is intended to avoid sending too many messages to the phone when it comes back online. Note that since there is no guarantee of the order in which messages get sent, the “last” message may not actually be the last message sent by the application server. Required.
data.<key> Payload data, expressed as key-value pairs. If present, it will be included in the Intent as application data, with the <key>. There is no  limit on the number of key/value pairs, though there is a limit on the total size of the  message. Optional.
delay_while_idle If included, indicates that the message should not be sent immediately if the device is idle. The server will wait for the device to become active, and then only the last message for each collapse_key value will be sent. Optional.
Authorization: GoogleLogin auth=[AUTH_TOKEN] Header with a ClientLogin Auth token. The cookie must be associated with the ac2dm service. Required.

This table lists the possible response codes:

Response Description
200 Includes body containing:

  • id=[ID of sent message]
  • Error=[error code]
    • QuotaExceeded — Too many messages sent by the sender. Retry after a while.
    • DeviceQuotaExceeded — Too many messages sent by the sender to a specific device. Retry after a while.
    • InvalidRegistration — Missing or badregistration_id. Sender should stop sending messages to this device.
    • NotRegistered — The registration_idis no longer valid, for example user has uninstalled the application or turned off notifications. Sender should stop sending messages to this device.
    • MessageTooBig — The payload of the message is too big, see the limitations. Reduce the size of the message.
    • MissingCollapseKey — Collapse key is required. Include collapse key in the request.
503 Indicates that the server is temporarily unavailable (i.e., because of timeouts, etc ). Sender must retry later, honoring any Retry-Afterheader included in the response. Application servers must implement exponential back off. Senders that create problems risk being blacklisted.
401 Indicates that the ClientLoginAUTH_TOKEN used to validate the sender is invalid.


Here are a few complete examples to get you started:

  • JumpNote. JumpNote is a sample two-way notes application, with auto-sync. JumpNote shows how to use the Android Cloud to Device Messaging Framework, as well as the Android Sync framework. JumpNote runs on top of Google App Engine, and it uses GWT for the web user interface.
  • Google Chrome to Phone Extension. “Chrome to Phone” lets  users send content from the Chrome browser to their mobile device.

To view the source code, open the Source tab and click Browse. From there, you can navigate through the source  tree.


C2DM imposes the following limitations:

  • The message size limit is 1024 bytes.
  • Google limits the number of messages a sender sends in aggregate, and  the number of messages a sender sends to a specific device

Reference :

How to Implement Push Notifications for Android


It’s been around 4 months now since I’ve started developing apps on the Android platform. It began with me scoring a free Nexus One phone at one of the Android Developer Labs.  Obviously, I couldn’t resist trying to hack around with some code, so I downloaded the SDK and dove in. I guess in some sense, that’s exactly what Google was hoping for when they starting giving out free phones. While it might sound like I got lucky, in the end Google is the one who won.

Anyway, developing for the Android platform turned out to the a pleasure. The SDK was easy to setup, easy to use and and easy to understand. Putting together your first app was a breeze. I was very impressed.

Unfortunately, I soon realized that Android is not perfect. One of the things that really disappointed me was the lack of a native method for performing push notifications. Over the past year push notifications became almost a standard in the mobile space thanks to Apple. Even though BlackBerry utlilized Push since god knows when, it was Apple that really brought Push mainstream. Obviously, lack of native Push on Android seems like a huge drawback. Naturally, I started looking around for a solution. After Googling through dozens and dozens of blogs and message boards, I’ve realized that there are 3 generally accepted ways to implement push notifications for your Android app. All of which are non-trivial, hacky and have their own disadvantages. Let’s go over the list:

  • Poll? The name obviously tells you that it’s really not even push. The idea here is to periodically poll the server for new messages from a background local or remote service. The more often you poll the closer you get to the real-time push.
Advantages: easy to implement. no cost solution
Disadvantages: Obviously, you will never be actually real-time. If you polling interval is 30 min, you can get a message that is 29 minutes and 59 seconds late. Moreover, polling more often than every 15-30 min will kill your battery pretty quickly:
  • SMS Android allows you to intercept SMS messages. Your server sends a specially encoded SMS to your phone, whenever there is something new. Your app intercepts all messages, looks for the ones from the server, then pops up a notification.
Advantages: easy to implement. Fully real-time updates. Known drop-in solutions exist such as one provided by Ericsson  Labs:
Disadvantages: Can be costly to you and the user. There are only a few services that allow you send around free SMS and even those are often limited to North America. If you want to have a reliable SMS-based service that is available worldwide, you will likely need to pay. Similar goes for the users. Not everyone has an SMS plan and you don’t want your users getting charged by 3rd party for using your app.
  • Persistent TCP/IP The phone initiates a long-lived mostly idle TCP/IP connection with the server and maintains it by occasionally sending keepalive messages. Whenever there is something new on the server, it sends a messages to the phone over the TCP connection.
Advantages: Fully real-time updates.
Disadvantages: Hard to implement a reliable service on both the phone and the server side. The Android OS is known to be able to kill services when it’s running low on memory, so your notifications service can easily disappear. What happens when your phone goes to sleep? Some people complain about battery life issues related to maintaining an active connection.

The first two methods have significant disadvantages that we cannot do anything about. However, the third method’s drawbacks are not as severe. It seems like with enough work and a good design, the persistent TCP/IP method can work. After all, that’s how GMail, GTalk and Google Voice implement their real-time updates. In fact, many developers out there agree that it is probably the best way to go until Google actually takes the matter in their own hands.

Persistent TCP/IP

After more Googling around I was able to come across three reasonable efforts to implement push notifications using a persistent TCP/IP connection:

While all of the work done by these guys is incredible, none of their results are quite ready for drop-in use by other developers. In my effort to implement push notifications, I decided to put the pieces of the puzzle together and combine their results to produce a relatively stable way of implementing push. The example that I provide you with further, is a combination of Josh Guilfoyle’s TestKeepAlive project and Dale Lane’s MQTT work. I borrow quite a bit of code from those guys, so they should get most of the credit.  Anyways, enough for the introduction, let’s get to the good stuff.

My Idea

The problem with the TestKeepAlive project is that it creates a raw TCP connection, which means that you need write your own server to take care of push on the other side. While it’s, without a question, doable, it is exactly why TestKeepAlive is far from a working solution. On the other hand, the MQTT example shown by Dale Lane uses the IBM’s MQTT broker to handle the server work. To backup a little, MQTT stands for MQ Telemetry Transport, which is a protocol developed by IBM. Let’s take a quick look at the man page:

mqtt is a publish/subscribe messaging protocol intended that is designed to be lightweight. It is useful for use with low power sensors, but is applicable to many scenarios.

Did you see the part about ‘low power’? So did I. Basically, the reason why one might consider using MQTT is that it was designed to be very lightweight, so that it doesn’t consume much power. This is ideal for a mobile push solution as it addresses many battery life related concerns about persistent TCP/IP connections. Obviously, MQTT also has some disadvantages such as privacy, but we can talk about that later.

So, my idea consists of taking a KeepAliveService and replacing the raw TCP/IP connection with an MQTT connection. In this case, each device can simply subscribe to a unique topic which is based on its device ID. Now, assuming that your server knows the device ID, it can push data to the device over MQTT by publishing to that unique topic.


In my example, I utilize a PHP script as a server. This uses the Simple Asynchronous Messaging  library (see project SAM to publish MQTT messages to the broker on which I host on my server. Let’s have a look at the overall system diagram:


wmqtt.jar is a simple drop-in implementation of MQTT protocol provided by IBM. It can be downloaded from The file that you download has a bunch of different stuff. Just look for the right jar file. You can include this jar as a part of your Android app.

Really Small Message Broker (RSMB) is a simple MQTT broker also provided by IBM It runs on port 1883 by default. In our architecture it accepts messages from the server and passes them on to the right devices. RSMB can also be replaced by the Mosquitto server

SAM is a drop-in PHP library for MQTT and other stuff. You can either get it as PECL extension or download the source online

send_mqtt.php is a simple PHP script that accepts messages over POST and uses SAM to pass-on messages to the broker.

Sample Code and Demo


The goal of my work on push notifications was to develop a working demo, which is what all other examples out there lack. I’m happy to say that I accomplished my objective. You can download the sample android app on GitHub.

This app (shown on the left) has a TextView and two buttons. The TextView contains your device ID and the buttons are used to start and stop the push notifications service. Once you have the app on your phone, start the service. Then go to and enter the device ID in the first text box and enter the message text in the textarea below. Press “Send Push Message” and you should get a notification on your phone. It’s as easy as that.

You can see the source code for andoid-push in this GitHub project. It contains the aforementioned send_mqtt.php script.

If you didn’t get a notification, make sure you have network connectivity. It can also be that the broker is down on my server (see server status on the page). If that’s the case, please post a comment and I will look into it bringing the broker back up.

Final Thoughts and Comments

MQTT is definitely not the best way to implement push for Android, but it does work. One of the main drawbacks of MQTT is that anyone who knows the IP and the PORT at which the broker is running can connect and intercept your Push messages. So it’s probably a good idea to encrypt them. Alternatively, you could write your own broker and introduce some sort of authentication to MQTT.

The code I provide here for the push service still needs more testing. Reliability is definitely the main question. I think the code can definitely be improved to better handle connectivity loss and other erroneous situations. You are welcome to post your comments here regarding how it can be improved.

Also let me know if you find any bad bugs. Good luck testing!

Anton Lopyrev

Reference :