Introduction

Purpose and Scope

This document provides technical guidelines to install and setup the OpenBack Platform within any native smartphone application for the Android mobile operating system.

Pre-requisites

This document is intended to be used by a developer with existing experience with Android Studio.

If your app (including the use of OpenBack) handles personal or sensitive user data (including personally identifiable information, microphone and sensitive device data) then your app must contain a privacy policy in the Play Developer Console (app listing) and within the app itself. Further details here.

Terminology

Library: Collective software components added into the mobile app

Description

The OpenBack Platform is a smart notification platform built on a real-time rules and reporting engine that automatically uses device and other context triggers (e.g., location, device time, other apps install, signal strength etc.) to send notifications and other messages e.g. interactive display messages, offline push notifications, SMS/text messages etc. and then manage and report on those messages in a user centric way, showing messages to users at the right moment.

The library syncs with the OpenBack Dashboard by downloading and storing the campaign context rules and related content locally and efficiently on the device, meaning notifications and messages work even without a data connection. Once the context triggers and other criteria are met, the device then displays the relevant message for the user to interact with. The Dashboard and Android library support over 30 trigger sets, and multiple trigger sets can be used in any of many campaigns - this means there are over 33 million potential trigger combinations.

The library polls data back to the platform as configured in the dashboard, by uploading the data to the OpenBack Engine (OBE) via HTTPS.

Overview of Process

OpenBack is a fast and easy integration for Android apps and should take less than 15 minutes for each app and involves:

  • Paste 2 lines of code into the app
  • Include AAR file in project
  • Add 2 lines to Gradle file
  • Update the manifest file

Android Step by Step Integration

  1. Add OpenBack maven repository to your application build.gradle
    repositories {
        maven { url 'https://maven.openback.com/public' }
    }
    
  2. Add OpenBack library to your application dependencies
    dependencies {
        ...
        compile "com.openback:OpenBack:2.+"
    }
    

Use the 2.+ format to make sure the latest library is picked up.

OpenBack is compiled with Google Services version 9.2.0 to support a wider range of devices but you can use a later version if you prefer.


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.

  1. 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"/> 
    
    

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

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

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

  5. 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" />

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

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

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

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

  10. 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 FCM/GCM

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

Only to be included if you not using GCM, add the following to the Manifest file:

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

If the application already handles FCM events with custom classes, make sure you call OpenBack. For example:

// In the application FCM Service class
public class FcmService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (!OpenBack.handleFcmMessage(getApplicationContext(), remoteMessage)) {
            // FCM Message was not handled by OpenBack
        }
    }
}
// In the application FCM InstandeId class
public class FcmInstanceIdService extends FirebaseInstanceIdService {
    @Override
    public void onTokenRefresh() {
        super.onTokenRefresh();
        OpenBack.refreshToken(getApplicationContext());
    }
}

GCM Settings

Not required for FCM - Only to be included if you use GCM, add the following to the Manifest file:

<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>
    ...
    <receiver android:name="com.google.android.gms.gcm.GcmReceiver" android:permission="com.google.android.c2dm.permission.SEND" android:exported="true">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
            <category android:name="" />
        intent-filter>
    receiver>
    <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 the application already handles GCM events with custom classes, make sure you call OpenBack. For example:

// In the application GCM Service class
public class GcmService extends GcmListenerService {
    @Override
    public void onMessageReceived(String from, Bundle data) {
        if (!OpenBack.handleGcmMessage(getApplicationContext(), from, data)) {
            // GCM Message was not handled by OpenBack
        }
    }
}
// In the application GCM InstandeId class
public class InstanceIDService extends InstanceIDListenerService {
    @Override
    public void onTokenRefresh() {
        // Pass the token event to OpenBack
        OpenBack.refreshToken(getApplicationContext());
    }
}

Initializing the OpenBack Library

  1. Note the OpenBack App Code for your application.
    The App Code is displayed in the Dashboard. You will need it when configuring the library.

    App Code


  2. Add the following line to each file that references OpenBack library

    import com.openback.OpenBack;
    import com.openback.UserInfoExtra;

  3. 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"));
      }
    }
  4. 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>


OpenBack Library API

These endpoints are used for your app to interact directly with OpenBack.

Getting the library version

String version = OpenBack.getSdkVersion();

Configuring the library

When starting OpenBack, the application provides a Config class with the following optional parameters:

// The user email address
setUserEmail(String email);
// The user mobile phone number
setUserMsisdn(String msidsn);
// The application FCM/GCM if you are not using the FCM/GCM gradle plugin
setGcmSenderId(String senderId);

Setting Custom Trigger values

OpenBack.setCustomTrigger(getContext(), OpenBack.CUSTOM_TRIGGER_1, "StringTest");
OpenBack.setCustomTrigger(getContext(), OpenBack.CUSTOM_TRIGGER_2, 42);
OpenBack.setCustomTrigger(getContext(), OpenBack.CUSTOM_TRIGGER_3, 1.12);

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

Extra user information

The application can pass some extra user information using the UserInfoExtra class by setting the following fields:

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

Instant Campaign Check

Although it is highly recommended to let OpenBack library decide when to check the campaigns, you can force it right away.

OpenBack.checkCampaignsNow(getContext());