Note that a full GCM implementation requires a server-side implementation, in addition to the client implementation in your app. This document offers a complete example that includes both the client and server.

Creating a Google API project

If you haven't created an API project yet, this page will prompt you to do so:

Note: If you already have existing projects, the first page you see will be the Dashboard page. From there you can create a new project by opening the project drop-down menu (upper left corner) and choosing Other projects > Create.

Click Create project.
Your browser URL will change to something like:

https://code.google.com/apis/console/#project:4815162342

Take note of the value after #project: (4815162342 in this example). This is your project number, and it will be used later on as the GCM sender ID.

Enabling the GCM Service

To enable the GCM service:

In the main Google APIs Console page, select Services.

Turn the Google Cloud Messaging toggle to ON.

In the Terms of Service page, accept the terms.

Obtaining an API Key

To obtain an API key:

In the main Google APIs Console page, select API Access. You will see a screen that resembles the following:

Click Create new Server key. Either a server key or a browser key should work. The advantage to using a server key is that it allows you to whitelist IP addresses. The following screen appears:

Click Create:

Take note of the API key value (YourKeyWillBeShownHere) in this example, as it will be used later on.

Note: If you need to rotate the key, click Generate new key. A new key will be created while the old one will still be active for up to 24 hours. If you want to get rid of the old key immediately (for example, if you feel it was compromised), click Delete key.

The following sections walk you through the steps of creating client and server-side code.

Writing a Client App

This section walks you through the steps involved in writing a client-side application—that is, the GCM-enabled application that runs on an Android device. This client sample is designed to work in conjunction with the server code shown in Writing the Server Code, below.

Step 1: Edit Your App's Manifest

The com.google.android.c2dm.permission.RECEIVE permission so the Android application can register and receive messages.

The android.permission.INTERNET permission so the Android application can send the registration ID to the 3rd party server.

The android.permission.GET_ACCOUNTS permission as GCM requires a Google account (necessary only if if the device is running a version lower than Android 4.0.4)

The android.permission.WAKE_LOCK permission so the application can keep the processor from sleeping when a message is received. Optional—use only if the app wants to keep the device from sleeping.

An applicationPackage + ".permission.C2D_MESSAGE" permission to prevent other Android applications from registering and receiving the Android application's
messages. The permission name must exactly match this pattern—otherwise the Android application will not receive the messages.

A receiver for com.google.android.c2dm.intent.RECEIVE, with the category set
as applicationPackage. The receiver should require the com.google.android.c2dm.SEND permission, so that only the GCM
Framework can send a message to it. Note that the receiving
of messages is implemented as an intent.

An intent service to handle the intents received by the broadcast receiver. Optional.

If the GCM feature is critical to the Android application's function, be sure to
set android:minSdkVersion="8" in the manifest. This
ensures that the Android application cannot be installed in an environment in which it
could not run properly.

Step 2: Register for GCM

An Android application running on a mobile device registers to receive messages by calling
the GoogleCloudMessaging method
register(senderID...).
This method registers the application for GCM and returns the registration ID. This streamlined approach replaces the previous
GCM registration process. See the example below for details.

Step 3: Write Your Application

Finally, write your application. GCM offers a variety of ways to get the job done:

To write your client application (that is, the GCM-enabled app that runs on an Android device), use the GoogleCloudMessaging APIs as shown below. Don't forget to set up your project to use the Google Play services SDK as described in Setup Google Play Services SDK.

Example

Here is a sample client application that illustrates how to use the GoogleCloudMessaging APIs. The sample consists of a main activity (DemoActivity) and a broadcast receiver (GcmBroadcastReceiver). You can use this client sample code in conjunction with the server code shown in Writing the Server Code.

Note the following:

The sample primarily illustrates two things: registration, and upstream messaging. Upstream messaging only applies to apps that are running against a CCS server; HTTP-based servers don't support upstream messaging.

The GoogleCloudMessaging registration APIs replace the old registration process, which was based on the now-obsolete client helper library. While the old registration process still works, we encourage you to use the newer GoogleCloudMessaging registration APIs, regardless of your underlying server.

Registering

An Android application needs to register with GCM servers before it can receive messages. So in its onCreate() method, DemoActivity checks to see whether the app is registered with GCM and with the server:

If the registration ID doesn't exist, or the app was updated, or the registration ID has expired, getRegistrationId() returns an empty string to indicate that the app needs to get a new regID. getRegistrationId() calls the following methods to check the app version and whether the regID has expired:

If there isn't a valid existing registration ID, DemoActivity calls the following registerBackground() method to register. Note that because GCM methods are blocking, this has to take place on a background thread. This sample uses AsyncTask to accomplish this:

Sending a message

When the user clicks the app's Send button, the app sends an upstream message using the new GoogleCloudMessaging APIs. In order to receive the upstream message, your server should be connected to CCS. You can use the code shown in Writing the Server Code as a sample XMPP client to connect to CCS.

As described above in Step 1, the app includes a broadcast receiver for the com.google.android.c2dm.intent.RECEIVE intent. This is the mechanism GCM uses to deliver messages. When onClick() calls gcm.send(), it triggers the broadcast receiver's onReceive() method, which has the responsibility of handling the GCM message. In this sample the receiver's onReceive() method calls sendNotification() to put the message into a notification:

Writing the Server Code

Here is an example of a CCS server written in Python. You can use this in conjunction with the sample client code shown above. This sample echo server sends an initial message, and for every upstream message received, it sends a dummy response back to the application that sent the upstream message. This example illustrates how to connect,
send, and receive GCM messages using XMPP. It shouldn't be used as-is
on a production deployment. For examples of HTTP-based servers, see GCM Server.