Skip to content

Integration Guide

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.

Step by Step Integration

1 - Gradle Integration

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:2.+"
}

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": "",
    "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": "",
    "notification": {
        "icon_material": {
            "name": "ic_notification_icon",
            "type": "drawable",             
            "color": "#231F20"              
        },
        "light": {
            "color": "#FF4081",             
            "onMs": 500,                   
            "offMs": 1000                  
        },
        "vibrate": {
            "pattern": [ 100, 200,  100, 200 ] 
        },
        "sound": {
            "name": "ding",                 
            "type": "raw"                   
        }
    }
}

notification:resource R.<type>.<name>, color is the background color
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.

Optional Normal Permissions

These permissions are accepted by a user when the app is installed.

Activity Permissions

<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />

Add the Google Play Services location dependency in your gradle file:

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

Bluetooth Permissions

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-feature android:name="android.hardware.bluetooth" android:required="false" />

Unlock Permissions

<receiver android:name="com.openback.OpenBackReceiver" android:exported="true">
    <intent-filter>
        ...
        <action android:name="android.intent.action.USER_PRESENT" />
        ...
    </intent-filter>
</receiver>

Aeroplane Permissions

<receiver android:name="com.openback.OpenBackReceiver" android:exported="true">
    <intent-filter>
        ...
        <action android:name="android.intent.action.AIRPLANE_MODE" />
        ...
    </intent-filter>
</receiver>

Connectivity Permissions

<receiver android:name="com.openback.OpenBackReceiver" android:exported="true">
    <intent-filter>
        ...
        <action android:name="android.net.wifi.WIFI_STATE_CHANGED" />
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />          

        ...
    </intent-filter>
</receiver>

Battery Permissions

<receiver android:name="com.openback.OpenBackReceiver" android:exported="true">
    <intent-filter>
        ...
        <action android:name="android.intent.action.BATTERY_LOW" />
        <action android:name="android.intent.action.BATTERY_OKAY" />
        <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
        <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
        ...
    </intent-filter>
</receiver>

Optional User Prompted Permissions

Starting with Android 6.0, users have to explicitly grant some permissions during runtime, also known as dangerous permissions. Click here for more information.

Location Permissions

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

<uses-feature android:name="android.hardware.location" android:required="false" />
<uses-feature android:name="android.hardware.location.gps" android:required="false" />
<uses-feature android:name="android.hardware.location.network" android:required="false"/> 

Phone Permissions

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

<uses-feature android:name="android.hardware.telephony" android:required="false" />
<uses-feature android:name="android.hardware.telephony.gsm" android:required="false" />
<uses-feature android:name="android.hardware.telephony.cdma" android:required="false" />

<receiver android:name="com.openback.OpenBackReceiver" android:exported="true">
    <intent-filter> 
        ...
        <action android:name="android.intent.action.PHONE_STATE" />
        ...
    </intent-filter>
</receiver>

Noise Permissions

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-feature android:name="android.hardware.microphone" android:required="false" />

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.

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: 'com.google.gms.google-services'

Firebase Settings

Add the Firebase library dependency in your gradle file:

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

Add the following to the manifest in the application section:

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

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 {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (!OpenBack.handleFcmMessage(getApplicationContext(), remoteMessage)) {
            // FCM Message was not handled by OpenBack
        }
    }
}

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.

AppCode

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 {

    @Override
    public void onCreate() {
        super.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)
                .setExtraUserInfo(userInfoExtra)
                .setUserEmail("test@openback.com"));
  }
}

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.

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

Other Apps Trigger

The Other Apps trigger allows you to send notifications to users based on apps that they currently have installed. The Other Apps trigger for Android can be completely setup and controlled from the OpenBack dashboard. Head to your View Apps and select the app you would like to edit. Select the Other App Settings tab and choose to either search for your app or add it manually.

Manually Adding an Other App

To manually add an Other App, you must first get the package name for the app. If you don't know an app's package name, it can be found on the Google Playstore very easily.

Go to the Playstore page for the app you want and you can find the app package name in the URL after the id parameter. Just copy everything after id= in the URL.

Grabbing the Package Name

Once you have the app package name, head to the Other Apps settings tab of your app and fill out the details. Set the Other App Label field to the name of the app and then add your package name to the Other App Package Name field.

Setting Package Name

Goals

The OpenBack SDK can be used to track Goals. These can range from anything such as a user completing a signup process, to a user purchasing a product.

Every goal has six components:

  • Goal Code - This is a unique identifier for each goal.
  • Goal Name - A name to easily distinguish between each goal.
  • Goal Description - A short description of what the goal achieves.
  • Number of Steps - The number of steps required for the goal to be completed. For example, step 1 is a user viewing a product, step 2 is the user adding the product to their cart. Step 3 and goal completion is the user purchasing the product.
  • Conversion Window - The length of time after a notification is received that it can be attributed to a goal completion.
  • Default Goal Value - This sets how much the goal completion is worth.

You can find the steps to logging a goal in Android here.

Custom Values & User Info

Custom values and user info (including Identity) can all be used for personalised content within messages. Custom values are used to segment/trigger messages for users. Identity is used when integrating the OpenBack Client API into your backend systems.

Custom Values - Constants

Custom value triggers are set by your mobile app and used to trigger a message when the value set by the mobile app matches the value set in the message through the OpenBack Dashboard or Client API. The values set can also be used as personalised content within messages.

public final static int CUSTOM_TRIGGER_1
public final static int CUSTOM_TRIGGER_2
public final static int CUSTOM_TRIGGER_3
public final static int CUSTOM_TRIGGER_4
public final static int CUSTOM_TRIGGER_5
public final static int CUSTOM_TRIGGER_6
public final static int CUSTOM_TRIGGER_7
public final static int CUSTOM_TRIGGER_8
public final static int CUSTOM_TRIGGER_9
public final static int CUSTOM_TRIGGER_10

setCustomTrigger

public static void setCustomTrigger(Context context, int triggerIndex, String value)
public static void setCustomTrigger(Context context, int triggerIndex, int value)
public static void setCustomTrigger(Context context, int triggerIndex, float value)

Set a custom trigger value. Value can be String, int or float.
For the trigger index, see Custom Triggers list.

Example:

OpenBack.setCustomTrigger(getApplicationContext(), OpenBack.CUSTOM_TRIGGER_1, "StringTest");
OpenBack.setCustomTrigger(getApplicationContext(), OpenBack.CUSTOM_TRIGGER_2, 42);
OpenBack.setCustomTrigger(getApplicationContext(), OpenBack.CUSTOM_TRIGGER_3, 1.12);
OpenBack.setCustomTrigger(applicationContext, OpenBack.CUSTOM_TRIGGER_1, "StringTest")
OpenBack.setCustomTrigger(applicationContext, OpenBack.CUSTOM_TRIGGER_2, 42)
OpenBack.setCustomTrigger(applicationContext, OpenBack.CUSTOM_TRIGGER_3, 1.12f)

Available since: 2.0.0

OpenBack typically supports up to 10 custom values, if you need more please discuss with OpenBack or email integrations@openback.com

User Info

User Info can be used to personalise content within messages. The Identity (Identity – Custom User Identifier) is only used when you integrate the OpenBack Client API into your backend systems and want to message a user with that identity.

Class container for the user info.

Name Type Description
AddressLine1 String Address line 1
AddressLine2 String Address line 2
AdvertisingId String Advertising identifier set by the application
Age String Age
Country String Country
CountryCode String ISO-2 country code
State String State
DateOfBirth String Date of birth YYYY-MM-DD
FirstName String First name
Gender String Gender
OptInUpdates String Opting in for campaign updates "true"/"false"
PostCode String Postal code
Profession String Profession
Surname String Surname
Title String Title
City String City
Identity1 String Custom user identifier 1
Identity2 String Custom user identifier 2
Identity3 String Custom user identifier 3
Identity4 String Custom user identifier 4
Identity5 String Custom user identifier 5

Note on Custom User Identifiers:
Identity is for use with the OpenBack API. If you are not an OpenBack API client, don't use them. Identities are bound to the current OpenBack user, so changing any one of them will reset user and campaign usage. A usage example: when your application has users that can login and logout, you can set one of the Identity to a token used in your system to identify that user. Later on, using the OpenBack API, you can fetch details from that user.

Handling onNewIntent

When using Smart Push campaigns with a simple message or a URL and the URL cannot be opened by the system, OpenBack brings your application to the foreground when the notification is selected. If the application was already in the foregound, that step is skipped. If your application was in the background, the library launches the last known Activity with singleTop flag. If your activity overrides onNewIntent, you can check if it was from the OpenBack library by using:

protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    if(intent.getBooleanExtra(OpenBack.OPENBACK_TO_FRONT_EXTRA, false)) {
        // OpenBack trying to bring your app in the foreground - maybe skip doing a major refresh
    }
}

Setting up ProGuard rules?

There is no need to set up ProGuard rules regarding the OpenBack SDK. These rules are set in the SDK and are included in your app upon building.

App Inbox

The OpenBack Android SDK supports an App Inbox feature which allows users to read messages even after they have dismissed the notification. Your application is in charge of managing and displaying the messages. For more information on implementing this feature in your app, go here.

Release Notes

v2.4.3

  • Patch JobIntentService to avoid SecurityExceptions

v2.4.1

  • Merged OpenBackService and OpenBackJobService.
  • Merged OpenBackAssetService and OpenBackAssetJobService.

v2.4.0

Required dependencies:

implementation "com.google.code.gson:gson:2.8.5"
implementation "com.android.support:appcompat-v7:27.1.1"
implementation "com.android.support:support-annotations:27.1.1"
implementation "com.android.support:support-compat:27.1.1"

Optional dependencies:

implementation "com.google.android.gms:play-services-location:11.8.0"
implementation "com.google.firebase:firebase-messaging:11.8.0"
implementation "com.google.firebase:firebase-core:11.8.0"


On Android 8+, OpenBack uses JobScheduler with JOB_ID 2700 for the OpenBackService and 2701 for the OpenBackAssetService. If you are using the JobScheduler directly or from a 3rd party SDK, you might have some conflict when using the same JOB_ID. Let us know if it is the case.