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 !

Using IntelliJ (or any IDE) with command line tools for developing Android projects

Recently I did some Blackberry development, and started using IntelliJ for that. I liked the concept of having the IDE separate from the build environment. There is some extra work involved but it is convenient if you need a command line interface may be to automate your builds.

Anyways jumping directly into the topic. I have here put together somethings you will need to do to use your choice of IDE and build using android command line tools. Since I have started liking to work with IntelliJ, I will also mention some IntelliJ specific tweaks.

So, clearly there are 2 parts here: The IDE set up and the build setup.

For build set up, we can just use the 'android' command to create the project. So, if we have a project in mind say TestProject, we'll create it using the command :

android create project --target 8 --name TestProject --path ./TestProject --activity TestActivity --package com.foo.Test

You can know the target by issuing the command :

android list target

I will not go deep into what are the targets and why you need them. You can find this information on the Android Developers Website.

The create project command will generate a directory structure which will contain bunch of directories and some configuration files and the build.xml required by ant.

Before you create/import the project in your IDE, issue the "ant debug" command on this generated directory structure. This will generate the R.java file which is the resource file which is needed for compiling along with your source files.

If you come from the Eclipse world, you know that there is a "workspace" in which there can be multiple "projects". Analogous to that, in IntelliJ, there is a "Project" in which there can be multiple "modules".

Talking in terms of IntelliJ, create an empty project (without any modules).

Now,

- Click File -> New Module

- In the Add Module dialog, see that "Create module from scratch" is selected. Click next

- In the Content Root field, browse to the root of this project. The name field will automatically be updated. Click Next

- It will mark the TestProject/src and the TestProject/gen directories as the source directories. This is what we want and this is why we ran the build process before creating the process. If you haven't run the build command before, it will only show the "src" directory. In that case, after you create the project, run the ant command and then come back to the module properties and mark the "gen" folder as a source folder. Doing this is important, or else it will never resolve the R.java references and is quite frustrating.

- Click Next and then Finish.

Now that we have added a new module, we'll need to add android libraries so that we can get intellicense !

- Right click on the module, go to Module Settings.

- Click on dependencies tab.

- Click Add -> Module Libraries

- Click Attach Jar Directories

- Select the specific android platform directory (that you used for creating the project with --target) For us that will be android-8 and will be located at ${ANDROID_SDK}/platforms/android-8

Select this path. Click OK twice. Click Apply.

You are all set !! But wait. There is still a trick pending !

Any time you change any of the resource files, the R.java will be outdated. No issues while building, but the IDE will start cribbing. The Eclipse plugin takes care of updating th R.java. For IntelliJ or other IDEs it might be irritating to see those unresolved references. Not just irritating to see, but some IDEs constantly bug with pop ups for unresolved references. A common mistake will be to import the generic "android.R" package ! In this case, the "R" reference will be resolved but won't find any of user defined resources.

So, each time when you add a resource, you'll need to build by issuing the ant command. But, many times the code is not complete and there is not point running the whole build. All we need is the command to generate the R.java file.

Simple, before writing any code, just run the ant command with the verbose output turned on. E.g. ant -v debug

In the -pre-build target, you will find the command for generating the R.java file. An example is as follows :

-pre-build:

-resource-src:

[echo] Generating R.java / Manifest.java from the resources...

[null] Current OS is Windows 7

[null] Executing 'C:\android-sdk_r07-windows\android-sdk-windows\platforms\android-8\tools\aapt.exe' with arguments:

[null] 'package'

[null] '-f'

[null] '-m'

[null] '-M'

[null] 'C:\androidworkspace\TestProject\AndroidManifest.xml'

[null] '-S'

[null] 'C:\androidworkspace\TestProject\res'

[null] '-I'

[null] 'C:\android-sdk_r07-windows\android-sdk-windows\platforms\android-8\android.jar'

[null] '-J'

[null] 'C:\androidworkspace\TestProject\gen'

[null]

[null] The ' characters around the executable and arguments are

[null] not part of the command.

Now, all you need to do is extract and form command from this and put it in a batch file (or shell script) and whenever you add any resources, just run the batch file in order to generate the R.java

Hope this helps someone !