Set up a GCM Client App on Android

A Google Cloud Messaging (GCM) Android client is a client app that runs on an Android device. To write your client code, we recommend that you use the GoogleCloudMessaging API and Android Studio with Gradle.

Here are the requirements for running a GCM Android client:

GCM requires devices running Android 2.2 or higher that also have the Google Play Store application installed, or an emulator running Android 2.2 with Google APIs. Note that you are not limited to deploying your Android applications through Google Play Store.
However, if you want to continue to use new GCM features that are distributed through Google Play Services, the device must be running Android 2.3 or higher, or you can use an emulator running Android 2.3 with Google APIs.
On Android devices, GCM uses an existing connection for Google services. For pre-3.0 devices, this requires users to set up their Google accounts on their mobile devices. A Google account is not a requirement on devices running Android 4.0.4 or higher.

A full GCM implementation requires both a client implementation and a server implementation. For more information about implementing the server side, see About GCM Connection Server.

The following sections walk you through the steps involved in writing a GCM client-side application on Android. At a minimum, a GCM client app must include code to register (and thereby get a registration token), and a receiver to receive messages sent by GCM. To review sample code for a simple GCM-enabled Android app, see the Quick Start Sample.

For existing apps that extend a WakefulBroadcastReceiver, Google recommends migrating to GCMReceiver and GcmListenerService. To migrate:

In the app manifest, replace your GcmBroadcastReceiver with "com.google.android.gms.gcm.GcmReceiver", and replace the current service declaration that extends IntentService to the new GcmListenerService
Remove the BroadcastReceiver implementation from your client code
Refactor the current IntentService service implementation to use GcmListenerService

For details, see the example manifest and code samples in this page.

Get a configuration file

Click the button below to get a configuration file to add to your project.

The configuration file provides service-specific information for your app. To get it, you must select an existing project for your app or create a new one. You'll also need to provide a package name for your app.

Get a Configuration File

Add the configuration file to your project

Copy the google-services.json file you just downloaded into the app/ or mobile/ directory of your Android Studio project. Open the Android Studio Terminal pane:

Mac/Linux

$ mv path-to-download/google-services.json app/

Windows

$ move path-to-download/google-services.json app/

The Google Services plugin for Gradle parses configuration information from the google-services.json file. Add the plugin to your project by updating your top-level build.gradle and your app-level build.gradle files as follows:

Add the dependency to your project-level build.gradle:

classpath 'com.google.gms:google-services:2.0.0-alpha6'

Add the plugin to your app-level build.gradle:

apply plugin: 'com.google.gms.google-services'

Set Up Google Play Services

To write your client application, use the GoogleCloudMessaging API. To use this API, you must set up your project to use the Google Play services SDK, as described in Set up Google Play Services SDK.

When you add the GCM Play Services library to your project, be sure to add it with resources, as described in Set up Google Play Services SDK. The key point is that you must reference the library—simply adding a .jar file to your project will not work. If you're using Android Studio, this is the string to add to the dependency section of your application's build.gradle file:

dependencies {
  compile "com.google.android.gms:play-services-gcm:8.4.0"
}

Edit Your Application's Manifest

Add the following to your application's manifest:

Your <application-package-name> + ".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 declaration of GcmReceiver, which handles messages sent from GCM to your application. Because this service needs permission to receive messages from GCM, add com.google.android.c2dm.permission.SEND to the receiver.
A declaration of GcmListenerService, which enables various aspects of handling messages such as detecting different downstream message types, determining upstream send status, and automatically displaying simple notifications on the app’s behalf.
A service that extends InstanceIDListenerService, to handle the creation, rotation, and updating of registration tokens.
Optionally, the android.permission.WAKE_LOCK permission if the application needs to keep the processor from sleeping when a message is received.
If the GCM feature is critical to the Android application's function, be sure to set android:minSdkVersion="8" or higher in the manifest. This ensures that the Android application cannot be installed in an environment in which it could not run properly.

Here is an example manifest that supports GCM:

<manifest package="com.example.gcm" ...>

    <uses-sdk android:minSdkVersion="8" android:targetSdkVersion="17"/>
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <permission android:name="<your-package-name>.permission.C2D_MESSAGE"
        android:protectionLevel="signature" />
    <uses-permission android:name="<your-package-name>.permission.C2D_MESSAGE" />

    <application ...>
        <receiver
            android:name="com.google.android.gms.gcm.GcmReceiver"
            android:exported="true"
            android:permission="com.google.android.c2dm.permission.SEND" >
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <category android:name="com.example.gcm" />
            </intent-filter>
        </receiver>
        <service
            android:name="com.example.MyGcmListenerService"
            android:exported="false" >
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            </intent-filter>
        </service>
        <service
            android:name="com.example.MyInstanceIDListenerService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.android.gms.iid.InstanceID" />
            </intent-filter>
        </service>
    </application>

</manifest>

If you want to support pre-4.4 KitKat devices, add the following action to the intent filter declaration for the receiver:


<action android:name="com.google.android.c2dm.intent.REGISTRATION" />

Check for Google Play Services APK

Apps that rely on the Play Services SDK should always check the device for a compatible Google Play services APK before accessing Google Play services features. It is recommended to do this in two places: in the main activity's onCreate() method, and in its onResume() method. The check in onCreate() ensures that the app can't be used without a successful check. The check in onResume() ensures that if the user returns to the running app through some other means, such as through the back button, the check is still performed. If the device doesn't have a compatible Google Play services APK, your app can call GooglePlayServicesUtil.getErrorDialog() to allow users to download the APK from the Google Play Store or enable it in the device's system settings. For a code example, see Set up Google Play Services SDK.

Obtain a registration token

An Android application needs to register with GCM connection servers before it can receive messages. When an app registers, it receives a registration token and sends it to the app server. The client app should store a boolean value indicating whether the registration token has been sent to the server.

Google provides the Instance ID API to handle the creation and updating of registration tokens. To use this API, include InstanceIDListenerService in the manifest:

<service android:name="[.MyInstanceIDService]" android:exported="false">
  <intent-filter>
         <action android:name="com.google.android.gms.iid.InstanceID"/>
  </intent-filter>
</service>

To obtain a token, call instanceID.getToken, providing the app server's sender ID and setting the scope to GoogleCloudMessaging.INSTANCE_ID_SCOPE. Do not call this method in the main thread; instead, use a service that extends IntentService as shown:

Once you've received your registration token, make sure to send it to your server.

The listener service's onTokenRefresh method should be invoked if the GCM registration token has been refreshed:

Once onTokenRefresh is called, use InstanceID.getToken() to get a new registration token, and then send the new token to your app server.

See the Instance ID API reference for full detail on this API.

Next steps

Once the client app is connected, you are ready to start receiving downstream messages and sending upstream messages. For more information about your options with GCM, see also guides for topic messaging and device group messaging as well as the reference information for both client and server APIs.