Android Integration Guide

OpenBack Android SDK version 4.1.0

Adding the OpenBack SDK to your Android apps is simple. It should take less than 15 minutes for each app and involves:

  • Add 2 lines to your Gradle files
  • Update the app manifest file

The SDK is a tiny ~230kB.

For a quick walkthrough of the integration, you can watch our tutorial video below.

info

A sample application is available on Github.

Migration and Deprecated SDK

For migrating from a previous version of the iOS SDK, click here.

For integrating a previous version of the SDK, click here.

tip

If you use any background services, make sure to check the app state before performing processes as the OpenBack SDK frequently runs in the background

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.1.0"
}

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

2 - Add the App Code to the Manifest

2.1 - Open the Dashboard

tip

If you have already created your app in the dashboard then you can skip to step 2.2

If you have Quick Start enabled, you can quickly create a new app. Add your App Package Name and App Name to the Quick Start section.

Quick Start Step 1

After creating your app, you will be brought to the settings page for that app. From here you can copy your App Code and add it to your AndroidManifest.xml.

Quick Start Step 2

2.2 - Adding the App Code to the Manifest

You can find the unique App Code for your application in the Dashboard.

AppCode

Copy that code for the next step.

tip

If you can't see your app in the App Settings page, make sure you have Demo Mode disabled!

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

NameTypeDescription
com.openback.APP_CODEStringYour application's OpenBack app code.
com.openback.AUTO_STARTBooleanIf true, OpenBack will start automatically. (Default: true)
com.openback.notification.ICONResourceIDThe resource ID for the notification icon.

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">
...
</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" />
</application>
</manifest>

Initialize the OpenBack SDK with your app context

The SDK uses a provider to initialize with the application context automatically. Under certain conditions, some vendors might block execution, resulting in an IllegalStateException. We recommend calling initialize() before using OpenBack in your application.

If you do not provide an App Code in the manifest, you can set it using the SDK API.

public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
setupOpenBack();
}
private void setupOpenBack() {
// Don't block the main thread in case OpenBack is not initialized
AsyncTask.execute(new Runnable() {
@Override
public void run() {
OpenBack.initialize(getApplicationContext())
// Optional if you already provide the app code in the manifest
OpenBack.setAppCode("YOUR_APP_CODE");
// Optional if you set auto start to true (default) in the manifest
OpenBack.start();
}
});
}
}

Check the API Docs for more info.

3 - Add support for Firebase Cloud Messaging

note

We recommend using FCM but it is not required. See more

3.1 - Firebase Integration

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'
  • Add the Firebase Messaging library dependency to your application build.gradle:
dependencies {
implementation "com.google.firebase:firebase-messaging:21.0.1"
}

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

3.2 - Add Firebase Service Handler

The following service is already declared in the library:

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

If you already have a custom service to handle Firebase Messaging events:

  • Make sure the priority is higher than the intent provided by the OpenBack SDK
  • Remove the <service android:name="com.openback.service.OpenBackFirebaseMessagingService"> from the manifest
  • In your service, call OpenBack when receiving a message or handling a new token:
public class YourFcmService extends FirebaseMessagingService {
@Override
public void onNewToken(String token) {
super.onNewToken(token);
OpenBack.refreshFcmToken(token);
...
}
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
// Check if the message is for the OpenBack service
if (OpenBack.handleFcmMessage(remoteMessage.getData())) {
// FCM message is handled by OpenBack
return;
}
...
}
}

4 - Verifying the OpenBack Integration

Running your app will register your device as a user to the OpenBack platform. You can verify that this is working by going to the Verify Latest Installs section within the App Setup tab in your App Settings. If your device has registered, then you are ready to send messages.

Checking Recent Users

When you can see your device registered within this section, follow our guide to create your first push message.

note

If you use the KeyChain library, make sure to read the FAQ

Advanced Features

For integrating features from a previous version of the SDK, click here.

FeatureOverview
Signals & PermissionsAdd the required settings and permissions in your manifest for signals.
AttributesAttribute values can be set client side by your mobile app, and then used as personalized content within messages.
Custom SegmentsCustom segments are set client side by your mobile app. They can be used to deliver a message based on the value set in your message campaign which is managed through the OpenBack Dashboard or Client APIs.
GoalsGoals can range from anything such as a user completing a signup process, to a user purchasing a product.
EventsAn event is a user action which is used to deliver a notification. You can pass existing or new events to the OpenBack SDK client-side, making advanced campaigns simple.
App InboxDeliver & manage messages in an inbox within your app – standalone, or as part of a notification.
TopicsMessage users that are subscribed to specific topics.
NotificationsCustomize the appearance of OpenBack notifications.