Push notifications on Android for Programmable Chat

Push notifications are integral to the mobile experience. The Android Programmable Chat SDK supports push notifications using GCM and FCM. Managing your push credentials is necessary because your registration token is required for the Chat SDK to send notifications through GCM or FCM.

In this guide, you will learn how to manage your push credentials to enable push notifications for the Android Programmable Chat SDK.

Before you begin, ensure you have the following:

• A Twilio account
• An Android app using the Programmable Chat SDK
• A Google account to access GCM or FCM

Important: The default enabled flag for new Service instances for all push notifications is false. This means that push notifications are disabled until you explicitly enable them. See Push Notification Configuration to enable push notifications for your Service instance.

Both GCM and FCM services look for a file called google-services.json in your Android app to identify push configuration details. Google provides a web interface for generating this file. For GCM, see Add Firebase to your Android project. For FCM, you can generate the file from the Firebase Console.

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

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

Expand image

After entering your app credentials, download the generated google-services.json file to your desktop. Save the API key that is displayed on the last page, as we'll use it later.

Android Studio uses Gradle to parse your credentials from the google-services.json file. Your app has two build.gradle files: a project-level one (global) and an app-level one (inside the app/ directory).

Add this line to buildscript dependencies in your project-level build.gradle:

classpath 'com.google.gms:google-services:3.0.0'

Add this line to the end of your app-level build.gradle:

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

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

compile 'com.google.android.gms:play-services:9.0.0'

Note: Be sure to use the com.android.tools.build:gradle:2.1.2 build plugin with Gradle, not com.android.tools.build:gradle-experimental:0.7.0. The latter will not work with the Google Services plugin and will not process your JSON file. If you need to use gradle-experimental, you will have to implement JSON parsing yourself or hardcode the Sender ID.

You need to import the Google Play Services and Firebase Messaging SDKs for your client to communicate with FCM. Add the following lines to the dependencies section of your app-level build.gradle:

1
compile 'com.google.firebase:firebase-messaging:10.2.0'
2
compile 'com.google.android.gms:play-services-base:10.2.0'

Note: Use version 10.2.0 or later, as earlier versions will not work.

The application manifest file defines critical information like permissions and dependency versions for the Android app before it runs any code. You need to add a few lines to configure your app to communicate with Google's push service.

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

1
<permission android:name="<your-package-name>.permission.C2D_MESSAGE"
2
    android:protectionLevel="signature" />
3
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
4
<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:

1
<receiver
2
    android:name="com.google.android.gms.gcm.GcmReceiver"
3
    android:exported="true"
4
    android:permission="com.google.android.c2dm.permission.SEND" >
5
    <intent-filter>
6
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
7
        <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
8
        <category android:name="<your-package-name>" />
9
    </intent-filter>
10
</receiver>

You'll also want to add the GcmListenerService to handle messaging-related events. An example implementation can be seen here.

1
<service
2
    android:name=".MyGcmListenerService"
3
    android:exported="false" >
4
    <intent-filter>
5
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
6
    </intent-filter>
7
</service>

Create a service that extends InstanceIDListenerService to handle registration tokens. An example implementation can be seen here.

1
<service
2
    android:name=".MyInstanceIDListenerService"
3
    android:exported="false">
4
    <intent-filter>
5
        <action android:name="com.google.android.gms.iid.InstanceID" />
6
    </intent-filter>
7
</service>

Add a service to handle subscriptions to GCM. See here for an example implementation.

1
<service
2
    android:name=".RegistrationIntentService"
3
    android:exported="false">
4
</service>

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, ensure the minimum SDK version is set to 8 or higher so that GCM works properly:

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

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

1
<permission android:name="<your-package-name>.permission.C2D_MESSAGE"
2
    android:protectionLevel="signature" />
3
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
4
<uses-permission android:name="<your-package-name>.permission.C2D_MESSAGE" />

You'll also want to add the FCMListenerService to handle events related to messaging. An example implementation can be seen here.

1
<service
2
    android:name=".FCMListenerService">
3
    <intent-filter>
4
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
5
    </intent-filter>
6
</service>

With FCM, you can set defaults for values that may be missing from incoming notifications. The notification background color and icon can be set like this:

1
<meta-data
2
    android:name="com.google.firebase.messaging.default_notification_icon"
3
    android:resource="@drawable/ic_launcher" />
4
<meta-data
5
    android:name="com.google.firebase.messaging.default_notification_color"
6
    android:resource="@color/darkred" />

Create a service that extends InstanceIDListenerService to handle registration tokens. An example implementation can be seen here.

1
<service
2
    android:name=".FCMInstanceIDService"
3
    android:exported="true">
4
    <intent-filter>
5
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
6
    </intent-filter>
7
</service>

Add a service to handle subscriptions to FCM. See here for an example implementation.

1
<service
2
    android:name=".RegistrationIntentService"
3
    android:exported="false">
4
</service>

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, ensure the minimum SDK version is set to 8 or higher so that FCM works properly:

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

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

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

The final step is to ensure that your Chat Android client Access Token includes the correct credential_sid—the one you created in Step 5 above. Each of the Twilio Helper Libraries enables you to add the push_credential_sid. Please see the relevant documentation for your preferred Helper Library for the details. Here is an example using the Node.js Twilio helper library:

1
var chatGrant = new ChatGrant({
2
    serviceSid: ChatServiceSid,
3
    pushCredentialSid: GCM_or_FCM_Credential_Sid,
4
});

Depending on whether you use GCM or FCM (you cannot use both at the same time), you need to call the correct ChatClient API methods—registerGCMToken and unregisterGCMToken for GCM, or registerFCMToken and unregisterFCMToken for FCM. See the Twilio Chat Android SDK documentation for details.

That's all we need to make sure the client has access to your registration token.

For information on configuring push notifications on the web, see Notifications on web.