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.

Note: Android C2DM will ultimately be available to all developers. However, it is currently launched in Labs, and not universally available. If you're interested in using C2DM with your Android applications, go to the signup page to request access. Google will contact you when you've been granted access.

Contents

1. Introduction
2. Architectural Overview
   1. Lifecycle Flow
   2. What Does the User See?
3. Writing Android Applications that use C2DM
   1. Creating the Manifest
   2. Registering for C2DM
   3. Unregistering from C2DM
   4. Handling Registration Results
   5. Handling Received Data
   6. Developing and Testing Your Applications
4. Role of the Third-Party Application Server
   1. How the Application Server Sends Messages
5. Examples
6. Limitations

Introduction

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.

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 (com.google.android.c2dm.intent.REGISTER) 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 a REGISTRATION Intent 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, see Role 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 com.google.android.c2dm.intent.RECEIVE 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 com.google.android.c2dm.intent.C2D_MESSAGE and com.google.android.c2dm.intent.REGISTRATION.

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:

• com.google.android.c2dm.permission.RECEIVE 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 com.google.android.c2dm.intent.RECEIVE and com.google.android.c2dm.intent.REGISTRATION, with the category set as applicationPackage. The receiver should require the com.google.android.c2dm.SEND 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 is an example of 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="com.google.android.c2dm.permission.RECEIVE" /> 
 
<!-- Send the registration id to the server --> 
<uses-permission android:name="android.permission.INTERNET" /> 
 
<!-- 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="com.google.android.c2dm.permission.SEND"> 
    <!-- Receive the actual message --> 
    <intent-filter> 
        <action android:name="com.google.android.c2dm.intent.RECEIVE" /> 
        <category android:name="com.example.myapp" /> 
    </intent-filter> 
    <!-- Receive the registration id --> 
    <intent-filter> 
        <action android:name="com.google.android.c2dm.intent.REGISTRATION" /> 
        <category android:name="com.example.myapp" /> 
    </intent-filter> 
</receiver>

Registering for C2DM

An Android application needs to register with C2DM servers before receiving any message. To register it needs to send an Intent (com.google.android.c2dm.intent.REGISTER), 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("com.google.android.c2dm.intent.REGISTER"); 
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("com.google.android.c2dm.intent.UNREGISTER"); 
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 com.google.android.c2dm.intent.REGISTRATION. It also defines a receiver for com.google.android.c2dm.intent.RECEIVE. 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 error parameter 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 REGISTRATION Intent:

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("com.google.android.c2dm.intent.REGISTRATION")) { 
        handleRegistration(context, intent); 
    } else if (intent.getAction().equals("com.google.android.c2dm.intent.RECEIVE")) { 
        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 the com.google.android.c2dm.intent.RECEIVE 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 https://android.apis.google.com/c2dm/send that includes the following:

This table lists the possible response codes:

Examples

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.

Limitations

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