Skip to content

Documentation Sections

1 - Add OpenBack using Gradle

Add OpenBack maven repository to your application build.gradle

repositories {
    maven { url 'https://maven.openback.com/public' }
}

Add OpenBack library to your application dependencies

dependencies {
    implementation "com.openback:OpenBack:4.0.0"
}

If you prefer to stay up-to-date with new features and enhancements, you can use the 4.+ notation like this: implementation "com.openback:OpenBack:4.+"

2 - Add configuration to the Manifest

You can configure OpenBack in your application manifest using meta-data tags inside the <application> tag.

Setting the App Code

<meta-data android:name="com.openback.APP_CODE" android:value="YOUR_APP_CODE" />

Name Type Description
com.openback.APP_CODE String The OpenBack app code for your application.

Setting Auto-Start

<meta-data android:name="com.openback.AUTO_START" android:value="true" />

Name Type Description
com.openback.AUTO_START Boolean If true, OpenBack will start automatically provided it has a valid app code. (Default: true)

Customizing the Notification

<meta-data android:name="com.openback.notification.ICON" android:resource="@drawable/ic_stat_name" />
<meta-data android:name="com.openback.notification.ACCENT_COLOR" android:resource="@color/colorPrimary" />
<meta-data android:name="com.openback.notification.LARGE_ICON" android:resource="@drawable/ic_launcher_foreground" />
<meta-data android:name="com.openback.notification.SOUND" android:resource="@raw/ding" />

Name Type Description
com.openback.notification.ICON Integer The resource ID for the notification icon.
com.openback.notification.ACCENT_COLOR Integer The resource ID for the notification color accent.
com.openback.notification.LARGE_ICON Integer The resource ID for the notification large icon.
com.openback.notification.SOUND Integer The resource ID for the notification sound.

Example:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.sample.app">
    <application ...>
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <meta-data android:name="com.openback.APP_CODE" android:value="YOUR_APP_CODE" />
        <meta-data android:name="com.openback.AUTO_START" android:value="true" />
        <meta-data android:name="com.openback.notification.ICON" android:resource="@drawable/ic_stat_name" />
        <meta-data android:name="com.openback.notification.ACCENT_COLOR" android:resource="@color/colorPrimary" />
        <meta-data android:name="com.openback.notification.LARGE_ICON" android:resource="@drawable/ic_launcher_foreground" />
        <meta-data android:name="com.openback.notification.SOUND" android:resource="@raw/ding" />

    </application>

</manifest>

Setting the app code using the API

If you do not provide an application code in the manifest, you can set it manually using the API.

public class SampleApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // Set the app code
        OpenBack.setAppCode("YOUR_APP_CODE");
        // Start OpenBack
        OpenBack.start();
  }
}

Check the API Docs for more info.

3 - Add support for Firebase Cloud Messaging

3.1 - Firebase Integration

  • Go to the Firebase console: https://console.firebase.google.com/.

  • Open your project settings page by clicking the cog wheel in the top left of the page and select Project Settings.

Firebase

  • Download the google-services.json file

Firebase

  • Add the json file to your android project /app folder.

  • Add the google services plugin at the end of the application build.gradle:

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

  • Finally add the firebase messaging library dependency in your application build.gradle:

dependencies {
    implementation "com.google.firebase:firebase-messaging:20.1.6"
}

For more details, check the official setup guide: https://firebase.google.com/docs/android/setup.

3.2 - Add Firebase Service Handler

Add the following to the manifest in the application section:

<service android:name="com.openback.OpenBackFcmMessagingService" android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

If you already have a custom service to handle Firebase Messaging events, do the following:

  • Remove the <service android:name="com.openback.OpenBackFcmMessagingService"> from the manifest
  • In your service, call OpenBack when receivng a message or handling a new token:

public class YourFcmService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String token) {
        super.onNewToken(token);
        OpenBack.refreshToken(token);
        ...
    }

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        // Check if the message is intented for the OpenBack service
        if (OpenBack.handleFcmMessage(remoteMessage.getData())) {
            // FCM Message was intented and handled by OpenBack
            return;
        }
        ...
    }
}

4 - Add Support for Location Services

If you use or plan to use location in your message triggers, you need to add the Google Play Service location library.

Add the following dependency in your application build.gradle:

dependencies {
    implementation "com.google.android.gms:play-services-location:17.0.0"
}

5 - 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

6 - Advanced Features and Permissions

The AndroidManifest.xml in OpenBack already contains a set of basic 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 integrations@openback.com 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.

For adding more features such as Attributes, Segments, Goals and Events, check out the Advanced Features page.