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.

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 or GCM).

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.

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>

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 (or previously Google Cloud Messaging - GCM). This in no way interferes with any existing FCM/GCM implementation or other analytics or push notification services.

After setting FCM/GCM 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

For GCM, the configuration file is available here. Follow instructions.

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

GCM Settings

Although now deprecated, if you prefer to use GCM over Firebase, follow these steps:

Add the Google Cloud Messaging library dependency in your gradle file:

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

If the application already handles GCM events with custom classes, make sure to call OpenBack first:

// In the application GCM Service class
public class YouGcmService extends GcmListenerService {
    @Override
    public void onMessageReceived(String from, Bundle data) {
        if (!OpenBack.handleGcmMessage(getApplicationContext(), from, data)) {
            // GCM Message was not handled by OpenBack
        }
    }
}

Otherwise, add the OpenBack GCM service to the Manifest:

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<uses-permission android:name=".permission.C2D_MESSAGE" />
<permission  android:name=".permission.C2D_MESSAGE" android:protectionLevel="signature" />

<application>
    ...
    <service android:name="com.openback.OpenBackGcmListenerService" android:exported="false">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        </intent-filter>
    </service>
    <service android:name="com.openback.OpenBackGcmInstanceIDListenerService" android:exported="false">
        <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID" />
        </intent-filter>
    </service>
    ...
</application>

If you do not use the google services plugin in gradle with google-services.json, make sure to pass the GCM Sender ID when starting OpenBack.

OpenBack.start(new OpenBack.Config(context).setGcmSenderId("YOUR_GCM_SENDER_ID"));

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.

User Data - Custom Values

UserInfoExtra

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

Constants - User Data - Custom Values

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

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.android.gms:play-services-gcm: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.