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 Gradle file
  • Update the manifest file
  • Paste 2 lines of code into the app

A sample application is available here.

Step by Step 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.+"
}

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 a known issue with Instant Run and compileOnly dependencies in external libraries.

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.

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.

Editing the application Android Manifest

Add the following to enable all triggers, feel free to remove sections if those triggers will never be used.

Starting with Android 6.0, users have to explicitly grant some permissions. Click here for more information.

If the application will use Location triggers, add the following:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_UPDATES" />
<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"/> 

If the application will use Activity trigger, add the following:

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

If the application will use Phone triggers, add the following:

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

<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" />
        <action android:name="android.intent.action.NEW_OUTGOING_CALL" />
        ...
    </intent-filter>
</receiver>

If the application will use SMS triggers, add the following:

<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-feature android:name="android.hardware.telephony" android:required="false" />

<application>
    ...
    <receiver android:name="com.openback.OpenBackSmsReceiver" android:permission="android.permission.BROADCAST_SMS">
        <intent-filter>

            <action android:name="android.provider.Telephony.SMS_RECEIVED" />
        </intent-filter>
    </receiver>
    ...
</application>

If the application will use Bluetooth triggers, add the following:

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

If the application will use Unlock triggers, add the following:

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

If the application will use Aeroplane triggers, add the following:

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

If the application will use Connectivity triggers, add the following:

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

If the application will use Battery triggers, add the following:

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

If the application will use Noise triggers, add the following:

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

Setting Up Firebase or Google Cloud Messaging

While campaigns/messages are sync’d out to each user as per the settings in the Dashboard, however to ensure instant delivery messages, immediately sync’ing new campaigns to users, 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"));

Initializing the OpenBack Library

Note the OpenBack App Code for your application. The App Code is displayed in the Dashboard. 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 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"));
  }
}

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.

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

Release Notes

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.