Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Configuring Android Push Notifications with GCM

In this guide, we'll go through all the necessary steps to get your Android push credentials configured with Twilio Notify. The end result is a Twilio Credential which you can then use to send notifications to your Android app. Let's get started!

Step 1 - Create a Configuration File

The GCM service looks for a file called 'google-services.json' in your Android app to identify it. Google provides an easy to use web interface to generate this file that you can find here.

Once you've gone through and entered in your app credentials, you can download the generated file to your desktop. Save the API Key that is displayed on the last page, we're going to use it later on.

Copy the 'google-services.json' file you just downloaded into the 'app/' directory of your Android Studio project.

Step 2 - Set up your project's dependencies

You can skip this step if using the quickstart app.

We have already preconfigured the quickstart app so you can just skip ahead to creating your credential.

Android Studio uses Gradle to parse your credentials from the 'google-services.json' file. Your app has 2 build.gradle files, a project-level one and an app-level one.

Add this line to your project-level build.gradle

classpath ''

Add this line to your app-level build.gradle

apply plugin: ''

You'll need to import the Google Play Services SDK for your client to be able to communicate with GCM. Add the following line to the dependencies section of the app-level build.gradle

compile ""

Step 3 - Edit the Application Manifest

You can skip this step if using the quickstart app.

We have already preconfigured the quickstart app so you can just skip ahead to creating your credential.

The Application Manifest file defines critical information like permissions and dependency versions for the Android app before it runs any code. You'll need to add in a few lines to configure your app to communicate with GCM.

Add the C2D_MESSAGE permission to prevent other Android apps from registering and receiving your messages.

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

Next, add the GcmReceiver to handle messages sent from GCM with the proper permissions enabled.

    android:permission="" >
        <action android:name="" />
        <category android:name="com.example.gcm" />

You'll also want to add the GcmListenerService to handle messaging related events

    android:exported="false" >
        <action android:name="" />

Once you've done that, create a service that extends InstanceIDListenerService, to handle registration tokens.

        <action android:name="" />

Make sure to add the WAKE_LOCK permission to keep the processor from sleeping when a message is received.

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

Lastly, make sure the minimum SDK version is set to 8 or higher so that GCM works properly

<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="17"/>

Step 4 - Upload your API Key to Twilio

Now that we have our app configured to receive push notifications, let's upload our GCM API Key by creating a Credential resource. Check out this page to generate a credential SID using the API key.

From the drop-down, choose GCM and paste in the key.

Step 5 - Configure your Twilio Service to use your API key

Twilio allows you to build multiple applications in a single account. To separate those applications you need to create Service instances that hold all the data and configuration for your application.

Specifically, you need to configure your Service instance to use the Credential that contains your GCM API key. You can do that using cURL and this resource.

You are ready to go. Check out the Android Quickstart for next steps.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.