Android Google Cloud Messaging Tutorial

Android Google Cloud Messaging Tutorial

android-gcm-archGoogle Cloud Messaging for Android (GCM) is a push-notification-like service freely provided by Google. Simply, it allows you to send data from one-end “we will call it a GCM server” to GCM clients e.g. Android app.

This service can be used to send notifications or messages containing up to 4Kb of payload data. The GCM service takes care of messages queueing and delivery to the target application. GCM is completely free no matter how big your messaging needs are, and there are “so far” no quotas.


Building a complete example showing how to enable GCM service, how to build GCM client “Android app” and how to build GCM server.

Environment & Tools:

  • Eclipse ADT
  • Emulator AVD, target: Google APIs – API Level 19


  • Jackson library to convert Java object to JSON

About the tutorial:

This tutorial is trying to cover all the needed steps to build a complete working example. As shown in the picture above we need to go over 4 steps:

  1. Go to Google Developers Console
  2. Build GCM Client “Android App”
  3. Build GCM Server “Java App”
  4. Run & Test
    • a. Register the Android app with GCM to receive Registration Id “RegId
    • b. Share “RegId” with the server
    • c. Send a message from server to GCM using HTTP POST request

( 1 ) Go to Google Developers Console

Google Developers Console is a place where you enable “activate” Google services that you want to integrate in your application. In this console you need to do the following:

  • 1.1 Create a Project
  • 1.2 Get Project Number
  • 1.3 Enable Google Cloud Messaging for Android
  • 1.4 Create Server API Key
  • 1.1 Create a Project

If this is the first time you visit Google Developer Console, you need to create a Project “A project consists of a set of applications, along with activated APIs, Google Cloud resources, and the team and billing information associated with those resources.”

  • Go to Developer Console home page
  • Click “CREATE PROJECT” button
  • Fill Project name “HMKCODE GCM”  & Project ID “hmkcode-gcm-project


  • 1.2 Get Project Number

    • Go to Developer Console home page
    • Click on the project name “HMKCODE GCM
    • At the top of the page yo will see Project Number
    • We we will need this number in Android app


  • 1.3 Enable Google Cloud Messaging for Android

    • Under the same project “HMKCODE GCM”
    • Click on API & auth >> API
    • Enable Google Cloud Messaginf for Android


  • 1.4 Create Serve API Key

  • Go to API & auth >> Credentials
  • Under Public API access click CREATE NEW KEYSelect Server Key
  • Click Create “leave the text box empty if you don’t have a specific IP address”
  • The Server API Key will be created
  • We will need this key in GCM Server



( 2 ) Build GCM Client “Android App”

  • 2.1 Create a new Android Project
  • 2.2 Create a Layout for MainActivity
  • 2.3
  • 2.4
  • 2.5
  • 2.6 AndroidManifest.xml
  • 2.1 Create a new Android Project

    • Application Name: Android GCM
    • Project Name: android-gcm-client
    • Package Name:
  • 2.2 Create Layout for MainActivity

The layout is so simple for this example. One Button to request registration ID and one EditText to display the registration ID “RegID


<LinearLayout xmlns:android=""
    android:orientation="vertical" >   

        android:text="Get RegId"/>

        android:layout_height="250dp" />

  • 2.3

  • /src/com/hmkcode/android/gcm/

This class has three functions

  • onCreate() : Loads the layout and get reference to Button and EditText
  • getRegId(): AsyncTask will register the app with GCM, receive registration id “RegID” & display it on EditText. Here you need to use the Project Number when communicating with GCM
  • onClick(): Listens to Button click event and call getRegId()

import android.os.AsyncTask;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;

public class MainActivity extends Activity implements OnClickListener {

    Button btnRegId;
    EditText etRegId;
    GoogleCloudMessaging gcm;
    String regid;
    String PROJECT_NUMBER = "102488860000";

    protected void onCreate(Bundle savedInstanceState) {

        btnRegId = (Button) findViewById(;
        etRegId = (EditText) findViewById(;

    public void getRegId(){
        new AsyncTask<Void, Void, String>() {
            protected String doInBackground(Void... params) {
                String msg = "";
                try {
                    if (gcm == null) {
                        gcm = GoogleCloudMessaging.getInstance(getApplicationContext());
                    regid = gcm.register(PROJECT_NUMBER);
                    msg = "Device registered, registration ID=" + regid;
                    Log.i("GCM",  msg);

                } catch (IOException ex) {
                    msg = "Error :" + ex.getMessage();

                return msg;

            protected void onPostExecute(String msg) {
                etRegId.setText(msg + "\n");
        }.execute(null, null, null);
    public void onClick(View v) {
    } }
  • 2.4

  • /src/com/hmkcode/android/gcm/

This is class will receive the GCM message & pass it to the GcmMessageHandler.


import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;

public class GcmBroadcastReceiver extends WakefulBroadcastReceiver {

    public void onReceive(Context context, Intent intent) {

        // Explicitly specify that GcmMessageHandler will handle the intent.
        ComponentName comp = new ComponentName(context.getPackageName(),

        // Start the service, keeping the device awake while it is launching.
        startWakefulService(context, (intent.setComponent(comp)));
  • 2.5

  • /src/com/hmkcode/android/gcm/

This class defines what to do with the received message. The received message will contain in its data part “as we will see later in GCM server step” two attributes title & message, we will extract “title” value from the intent extras & display it on a Toast.

  "data": {
    "title": "Test Title",
    "message": "Test Message"

import android.content.Intent;
import android.os.Bundle;
import android.os.Handler;
import android.util.Log;
import android.widget.Toast;

public class GcmMessageHandler extends IntentService {

     String mes;
     private Handler handler;
    public GcmMessageHandler() {

    public void onCreate() {
        // TODO Auto-generated method stub
        handler = new Handler();
    protected void onHandleIntent(Intent intent) {
        Bundle extras = intent.getExtras();

        GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(this);
        // The getMessageType() intent parameter must be the intent you received
        // in your BroadcastReceiver.
        String messageType = gcm.getMessageType(intent);

       mes = extras.getString("title");
       Log.i("GCM", "Received : (" +messageType+")  "+extras.getString("title"));



    public void showToast(){ Runnable() {
            public void run() {
                Toast.makeText(getApplicationContext(),mes , Toast.LENGTH_LONG).show();

  • 2.6 AndroidManifest.xml

You need to add five permissions, a receiver and service tags.

  • Permission .
  • Permission android.permission.INTERNET
  • Permission android.permission.GET_ACCOUNTS
  • Permission android.permission.WAKE_LOCK
  • Permission applicationPackage + ".permission.C2D_MESSAGE"
  • Receiver
  • Service
  • Meta-data for Google Play service version

To read more about each permission…

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android=""
    android:versionName="1.0" >

        android:targetSdkVersion="17" />

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="" />

    <permission android:name=""
        android:protectionLevel="signature" />
    <uses-permission android:name="" />


            android:label="@string/app_name" >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            android:permission="" >
                <action android:name="" />
                <category android:name="" />
        <service android:name=".GcmMessageHandler" />

        <meta-data android:name=""
           android:value="@integer/google_play_services_version" />


 ( 3 ) Build GCM Server “Java App”

GCM server can be an app “web, desktop or even mobile app”, or scheduled scripts that can establish HTTP connection with GCM and then send POST request instructing GCM to send a message to one or more registered GCM clients “mobile apps”.

The HTTP POST request should include two headers:

  • Authorization: key=SERVER API KEY
  • Content-Type: application/json for JSON; application/x-www-form-urlencoded;charset=UTF-8 for plain text.

HTTP POST body can be in JSON or plain text format. In this example we will use JSON format. Below is an example of what we will send in body of the request.

  "data": {
    "title": "Test Title",
    "message": "Test Message"
  "registration_ids": ["RegId", "another RegId if needed"] 
  • 3.1 Create a new Java Project
  • 3.2
  • 3.3
  • 3.4
  • 3.1 Create a new Java Project


  • 3.2 com/hmkcode/vo/

This is a simple POJO to hold POST body content “will be converted to JSON when sending the request”. Here we need to pass the following:

  1. RegIds: One or more RegId can be added
  2. title & message: Two strings which will form the data part of the content.
package com.hmkcode.vo;

import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

public class Content implements Serializable {

    private List<String> registration_ids;
    private Map<String,String> data;

    public void addRegId(String regId){
        if(registration_ids == null)
            registration_ids = new LinkedList<String>();

    public void createData(String title, String message){
        if(data == null)
            data = new HashMap<String,String>();

        data.put("title", title);
        data.put("message", message);
  • 3.3 com/hmkcode/

This class will send the POST request. Here we need to pass the following:

  1. Server API Key: this key will be added to POST headers.
  2. Content object which will be converted in JSON format using Jackson library
package com.hmkcode;

 import com.fasterxml.jackson.databind.ObjectMapper;
import com.hmkcode.vo.Content;

public class POST2GCM {

    public static void post(String apiKey, Content content){


        // 1. URL
        URL url = new URL("");

        // 2. Open connection
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();

        // 3. Specify POST method

        // 4. Set the headers
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("Authorization", "key="+apiKey);


            // 5. Add JSON data into POST request body

            //`5.1 Use Jackson object mapper to convert Contnet object into JSON
            ObjectMapper mapper = new ObjectMapper();

            // 5.2 Get connection output stream
            DataOutputStream wr = new DataOutputStream(conn.getOutputStream());

            // 5.3 Copy Content "JSON" into
            mapper.writeValue(wr, content);

            // 5.4 Send the request

            // 5.5 close

            // 6. Get the response
            int responseCode = conn.getResponseCode();
            System.out.println("\nSending 'POST' request to URL : " + url);
            System.out.println("Response Code : " + responseCode);

            BufferedReader in = new BufferedReader(
                    new InputStreamReader(conn.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();

            while ((inputLine = in.readLine()) != null) {

            // 7. Print result

            } catch (MalformedURLException e) {
            } catch (IOException e) {
  • 3.4 com/hmkcode/

Here we run the server and pass the needed parameters Server API Key, RegId & data (title & message)

package com.hmkcode;


import com.fasterxml.jackson.databind.ObjectMapper;
import com.hmkcode.vo.Content;

public class App 
    public static void main( String[] args )
        System.out.println( "Sending POST to GCM" );

        String apiKey = "AIzaSyB8azikXJKi_NjpWcVNJVO0d........";
        Content content = createContent();, content);

    public static Content createContent(){

        Content c = new Content();

        c.createData("Test Title", "Test Message");

        return c;

( 4 ) Run & Test

Note: If you are using an emulator to run the Android app make sure the target is Google APIs.


  • a. Register the Android app with GCM to receive Registration Id “RegId

  1. Run the Android app “built in step 2″
  2. Click Get RegId
  3. RegId will be displayed in EditText & also in LogCat
  4. Copy the RegId so we can use it in Server app.


  • b. Share “RegId” with the server

Server needs to know client(s) RegId(s) to whom the message will be sent to. Here for the sake of simplicity, our app will share RegId by manually copying it from the client and then “hard-coding” it in the server code  “copy and paste”. However, in a real world, your app needs to share its RegId with GCM server by for example “sending it using HTTP POST request”.

So just copy the RegId from LogCat window and paste it in the server class

// class
  • c. Send a message from server to GCM using HTTP POST request

Now, run class to send the POST request to GCM which will boradcast it to registered clients.


  • Client GCM Source Code @ GitHub
  • Server GCM Source Code @ GitHub

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s