Skip to content

Android Setup

OpenBack is a fast and easy integration for Android apps and should take less than 15 minutes for each app and involves:

  • Add 2 lines to your Gradle files
  • Add a JSON file for configuring OpenBack
  • Update the manifest file
  • Paste 2 lines of code into the app

The SDK, which is an AAR file, is a tiny 230 KB.

A sample application is available on Github here.

Often a cross team discussion before integration will help confirm what Custom Values, what Goals and which Other Apps triggers should be setup during OpenBack SDK integration. Contact the integrations team if you would like a simple template to document and agree these.

1 - Gradle Integration

Add OpenBack maven repository to your application build.gradle

repositories {
    maven { url '' }

Add OpenBack library to your application dependencies

dependencies {
    implementation "com.openback:OpenBack:3.+"

Gradle Integration

Use the 2.+ format to make sure the latest library is picked up. OpenBack is compiled with Google Play Services version 11.8.0 to support a wider range of devices but you can use a later version if you prefer.

Starting with 2.4.0, Google Play Services are compileOnly dependencies. It allows you to control the packages you want to use and reduce your application methods/fields count. Make sure to add the packages required for the triggers you plan to use (see below), and for the preferred push service (Firebase).

If you are using Android Studio 3.0 or 3.1, you might have to disable Instant Run. There is an issue, known to Google, with Instant Run and compileOnly dependencies in external libraries.

2 - Setting Configuration File

Add a configuration file named openback.json to the application assets folder. If the application doesn't have an assets folder, simply select the application module, right click and select File > New > Folder > Assets Folder

    "appCode": "<YOUR_APP_CODE>",
    "notification": {
        "icon_material": {
            "name": "ic_notification_icon",
            "type": "drawable",
            "color": "#231F20"

The notification parameter is used to customize the notification icon. It is important to set the material icon for devices using Android 5 and above, otherwise the displayed icon may look like a colored square. For more information, please refer to this page.

You can also customize the light, vibrations, and sound if you like:

    "appCode": "<YOUR_APP_CODE>",
    "notification": {
        "icon": {
            "name": "ic_notification_icon_prelollipop",
            "type": "drawable"
        "icon_material": {
            "name": "ic_notification_icon",
            "type": "drawable",             
            "color": "#231F20"              
        "bigIcon": {
            "name": "ic_large_icon"
        "light": {
            "color": "#FF4081",             
            "onMs": 500,                   
            "offMs": 1000                  
        "vibrate": {
            "pattern": [ 100, 200,  100, 200 ] 
        "sound": {
            "name": "ding",                 
            "type": "raw"                   

Notification customization:

  • icon: Small notification icon for pre Android 5. Resource R.<type>.<name>.
  • icon_material: Small notification icon for Android 5+.Resource R.<type>.<name>, color is the background color.
  • bigIcon: Large icon displayed in notification. Resource R.drawable.<name>.
  • light:light is the flashing led color, onMs is the flashing led ON time in ms, offMs is the flashing led OFF time in ms
  • vibrate:pattern is an array of ON/OFF vibration in ms
  • sound: resource R.<type>.<name>

When providing a sound resource, make sure it is in your application resources. Otherwise notifications will not make noise.

3 - Editing the Application Android Manifest

We recommend that you add all normal permissions that you are comfortable with and only add user prompted permissions if necessary. For a full list of Android permissions, go to the Optional Features page.

4 - Firebase/FCM Settings

As of April 2018, Google has officially deprecated GCM. We highly recommend you use Firebase instead. Find out more about the deprecation here.

To find your Firebase Cloud Messaging key, go to the Firebase console here. Go to your project settings page by clicking the cog wheel in the top left of the page and select Project Settings. Your Firebase key is in the Cloud Messaging tab. We recommend that you use the Server key but the Legacy server key will also work.

While campaigns/messages are synced with each user as per the settings in the Dashboard, to ensure instant delivery messages, immediately syncing new campaigns to users and using Intelligent Routing features or Instant Campaign Updates you need to setup Firebase Cloud Messaging - FCM. This in no way interferes with any existing FCM implementation or other analytics or push notification services.

After setting FCM for your application, a configuration file named google-services.json will be generated for the application. Put that configuration file in the /app folder.

For FCM, configuration file is available here. Select your project -> Settings (Gear) Button -> Project Settings -> google-services.json button

Add the following at the end of the application build.gradle:

apply plugin: ''

Firebase Settings

Add the Firebase library dependency in your gradle file:

dependencies {
    implementation ""

Add the following to the manifest in the application section:

<service android:name="com.openback.OpenBackFcmMessagingService">
        <action android:name="" />

If your application already handles Firebase events with a custom class:

  1. Remove the <service android:name="com.openback.OpenBackFcmMessagingService"> from the manifest

  2. Call the OpenBack Firebase handler first:

// In your application Firebase Service class
public class YourFcmService extends FirebaseMessagingService {
    public void onNewToken(String token) {
        Log.e("FIREBASE", "New token: " + token);
        OpenBack.refreshToken(getApplicationContext(), token);

    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (!OpenBack.handleFcmMessage(getApplicationContext(), remoteMessage.getData())) {
            // FCM Message was not handled by OpenBack
            Log.e("FIREBASE", "Not an OpenBack message");

NOTE: We recommend setting a priority for your custom class in the manifest as shown below.

<service android:name=".YourFcmService">
    <intent-filter android:priority="100">
        <action android:name="" />

NOTE: We usually allow 15 - 30 minutes for the device to register its push token with APNs/Firebase and for our backend system to sync up.

5 - Initializing the OpenBack SDK

Note the OpenBack App Code for your application. The unique App Code is displayed in the Dashboard and can be found here. You will need it when configuring the library.


Add the following line to each file that references OpenBack library

import com.openback.OpenBack;
import com.openback.UserInfoExtra;

Initialise OpenBack library class on the main thread by overriding the “onCreate” function in the Application class of the project with the following:

public class SampleApplication extends Application {

    public void onCreate() {
        Context context = getApplicationContext();

        // User Extra Info (see OpenBack Library API for more info)
        UserInfoExtra userInfoExtra = new UserInfoExtra();
        userInfoExtra.OptInUpdates = "true";
        // Initialize OpenBack
        OpenBack.start(new OpenBack.Config(context)

Initializing the SDK

If your app requires a user to login, make sure to start the OpenBack SDK when they login and similarly, stop the OpenBack SDK if they logout.

Verifying the OpenBack Integration

When you have completed the basic integration of the OpenBack SDK, running your app will register your device as a user to the OpenBack Engine. You can verify that this is working properly and that you're ready to send messages by going to the Developer Tab in your App Settings and checking that your device has registered.

Checking Recent Users

Configuring the OpenBack Library

The AndroidManifest.xml in OpenBack already contains the required set of Permissions, Services and Receivers. Gradle will merge it into the application manifest. For more information on manifest merge, check the following link. If you have any difficulties with the process, email for a quick response or message the live chat below.

It is recommended to include the device features (even if they are implied in most cases) to be fully compliant with the Play Store. Visit this page for more information.

Advanced Setup

For adding more features such as User Info and Goals, check out the Optional Features page.