Android C2DM Messaging (Server Push for Android Phones)

UPDATE: Added diagrams to get concepts clear.

From monday, I have been fighting to get the C2DM (Cloud to Device Messaging) working. And with somewhat frustration and a lot of help from some good people out there, I got it working ! :)

In this article I describe my findings and try to explain the concepts in simple words and list out steps you need to do to get it working. For an example code I would suggest you take a look at Gabor's blog which is  this. Its really awesome.!

NOTE: Also, I would suggest you to take a look at the sample code provided by google. If I get time, I will also post some sample code (don't wait for me to do that :D). Also, just take a look at the classes in the google.android.c2dm package provided in the sample codes. No need to dig into the details, but I may talk about them later in this post.

So what is C2DM ? It is a server push mechanism provided by Google so that 3rd party applications can push messages to their applications on Android devices. Currently as of today, it is in beta, and if you are an enterprise, you will need to apply and have talks with Google before having your application out with a lot of users and lot of messages to push. However, for developers with a gmail account ID, the registration request should be pretty easily accepted and you will be "whitelisted".

Before digging into details, let us see what are the top level concepts and which components are involved. Basically there are 3 entities involved:
0. The Google C2DM service.
1. Your server application. I'll call it as the "FOOServer". This will send the message to the C2DM service which will forward it to the requested device.
2. The application on the device that receives the message. I'll simply call it DeviceApp.

So, no points to guess that C2DM acts as a middle man and does the message passing. How ? It uses the default google services on the Android phone. So the basic requirement for this whole thing to work is that there should be at least one logged-in Google account from the device.

Now, when you signup for the C2DM, you will be providing them with the following (only 2 relevant things are mentioned):
1. The Application Name. This is actually the package name that you will provide. It is very important to remember this, because this is the package name you will have to use for your DeviceApp and worst part is that in the whitelisted mail that you get from Google, this is not mentioned. I haven't found a way to look at our registered information. If anyone knows this, please comment and let me and other know. So, for the time being consider that the package name is "com.foo.test"

2. The second important thing on the registration form is the Role Account Email ID. Make sure that this email is not used on any device. I have found that the messaging will not work for that device. So, for our example lets say it is FOO@gmail.com

Just for fun, the following diagram depicts the above step.

So, till now, we have the email account ID which is FOO@gmail.com and the package name.

Who needs what
Ok, so how does each entity react to the C2DM and what IDs and credentials does it use ?


DeviceApp

The device app registers with the C2DM service. It tells the C2DM service that it would like to receive messages from FOOServer. In return it gets back a registration ID.

So,
DeviceApp -----[FOO@gmail.com]------> C2DM

C2DM  --------[registrationID]--------> DeviceApp

The first action is done via a registration Intent. If you see the C2DMessaging class you will get this. Here, the DeviceApp sends the FOO@gmail.com address specifying that it would like to receive messages from this account.

Next, You will need to extend the C2DMBaseReceiver and override the onRegistered and onUnregistered methods. So, the onRegistered method will be called when the C2DM server accepts the registration. In this method you will receive a registrationID. This is a very long alpha numeric string that identifies the device.

Now, the DeviceApp needs to convey back this registration ID to the FOOServer. It is recommended that at this point you also send some unique device identifier to keep track on the FOOServer. The reason is that Google may change these registrationIDs and may not be unique. If Google changes any IDs it will push the new ID to the DeviceApp which has to handle it in similar fashion.

So, if you choose say IMEI/MEID as the unique identifier, then,


DeviceApp -----[UniqueID, registrationID]------> FOOServer


Thats it ! The device is now registered and ready to receive any messages. The following diagram shows this registration work flow:

Registration Work Flow

FOOServer:
The FOOServer will store (or update) the registrationID received into its local database. So, eventually the server will have registrationIDs from all the devices the DeviceApp is on. To send a message to a particular device, the FOOServer needs to POST to the C2DM Service the following four three things:
1. The accountName which will be FOO@gmail.com (Update : Thank you @matest for pointing it out that this is not needed)
2. An authentication Token [explained below]
3. The registrationID of the device it wants to send the message.
4. The message itself ( I think the limit is 1024 charcters)


You can get the authentication token by providing the credentials for FOO@gmail.com. I used curl to get the token. In our case the command would be :


curl https://www.google.com/accounts/ClientLogin -d Email=FOO@gmail.com -d "Passwd=FooPassWord" -d accountType=GOOGLE -d source=FOOServer -d service=ac2dm


[note this command is taken from comments posted on this blog]

Getting the auth token

This should give you few very long string values one of which would start with "Auth=". This is the one you want. Even if I have used curl here, it is recommended that you get the token programmability, because even this token might change. If it changes, the new token would be returned as a response to the POST that we do to send the message.

Sending the message

I would like to thank Gabor Paller for writing a very good article on this and helping me with this process. Also, thanks to DavidMyton for his article. The comments below this article are pretty useful too. I also found this discussion on c2dm google group helpful.

I have written this in a hurry. So let me know of any "bugs" in the article and I'll fix those  !!
Thank you !