Android Legacy API

This section is dedicated to the various functions available within previous versions of the OpenBack SDK.

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

Logging a Goal

To log a goal, first follow the steps on Goal Creation to set up your goal on the dashboard.

public static boolean logGoal(Context context, String goal, int step, double value)

At any point, you can log a goal that is associated with a campaign. Make sure to use the Goal code, not the Goal name.

Example:

OpenBack.logGoal(getApplicationContext(), "myGoalCode", 1, 102.5);
OpenBack.logGoal(applicationContext, "myGoalCode", 1, 102.5)
info

Available since: 2.3.0

Methods

checkCampaignsNow

public static void checkCampaignsNow(Context context)

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

Example:

OpenBack.checkCampaignsNow(getApplicationContext());
OpenBack.checkCampaignsNow(applicationContext)
info

Available since: 2.0.0

coppaCompliant

public static void coppaCompliant(Context context, boolean compliant)

If your application needs COPPA to be enabled, set the COPPA compliant status with this function. If COPPA is enabled, campaigns will not run unless compliant is set to true.

Example:

OpenBack.coppaCompliant(getApplicationContext(), true);
OpenBack.coppaCompliant(applicationContext, true)
info

Available since: 2.3.1

getAndroidMinSdkSupport

public static int getAndroidMinSdkSupport()

Returns the minimum android SDK level supported by the library.

Example:

int minSdk = OpenBack.getAndroidMinSdkSupport();
val minSdk = OpenBack.getAndroidMinSdkSupport()
info

Available since: 2.0.0

getAppCode

public static String getAppCode(Context context)

Returns the currently set OpenBack app code.

Example:

String appCode = OpenBack.getAppCode(getApplicationContext());
val appCode = OpenBack.getAppCode(applicationContext)
info

Available since: 3.0.4

getSdkVersion

public static String getSdkVersion()

Returns the current OpenBack version.

Example:

String version = OpenBack.getSdkVersion();
val version = OpenBack.getSdkVersion()
info

Available since: 2.0.0

gdprForgetUser

public static void gdprForgetUser(Context context, boolean forgetUser)

When your user requests that all the data should be erased, set this value to true. It will inform the OpenBack server to remove all logs for the current user. All future logs will be erased after processing. If you wish to be fully GDPR complient, you also need to enable GDPR in your application settings on the OpenBack Dashboard.

Example:

OpenBack.gdprForgetUser(getApplicationContext(), true);
OpenBack.gdprForgetUser(applicationContext, true)
info

Available since: 2.3.0

handleFcmMessage

public static boolean handleFcmMessage(Context context, Map<String, String> data)

When your application already uses Firebase message service class, call this method first to check if the message is intended for OpenBack.

Example:

public class YourFcmService extends FirebaseMessagingService {
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
if (!OpenBack.handleFcmMessage(getApplicationContext(), remoteMessage.getData())) {
// FCM Message was not handled by OpenBack
}
}
}
class YourFcmService : FirebaseMessagingService() {
override fun onMessageReceived(remoteMessage: RemoteMessage?) {
if (!OpenBack.handleFcmMessage(applicationContext, remoteMessage.getData())) {
// FCM Message was not handled by OpenBack
}
}
}
info

Available since: 2.0.0 - Parameters updated in 2.6.1 for optional dependencies

isStarted

public static boolean isStarted(Context context)

Returns true if OpenBack is running.

Example:

BOOL started = OpenBack.isStarted(getApplicationContext());
val started = OpenBack.isStarted(applicationContext)
info

Available since: 2.2.0

start

public static void start(Config config) throws OpenBackException

Start the OpenBack library on the device. For best results, it should be called on the main thread in your application class onCreate().

Example:

OpenBack.start(new OpenBack.Config(context)
.setExtraUserInfo(userInfoExtra)
.setUserEmail("test@openback.com"));
OpenBack.start(OpenBack.Config(applicationContext)
.setExtraUserInfo(userInfoExtra)
.setUserEmail("test@openback.com"))
info

Available since: 2.0.0

stop

public static void stop(Context context)

If you decide to opt-out of all notifications from OpenBack, call this function.
OpenBack will not run until start() is called again.

Example:

OpenBack.stop(getApplicationContext());
OpenBack.stop(applicationContext)
info

Available since: 2.2.0

update

public static void update(Config config) throws OpenBackException

Use this API to update the user info, including email / phone number / extra info. Updating the UserInfoExtra replaces the all previous values, so make sure to set all the fields needed each time.

Example:

UserInfoExtra userInfoExtra = new UserInfoExtra();
userInfoExtra.City = "Dublin";
OpenBack.update(new OpenBack.Config(context)
.setExtraUserInfo(userInfoExtra)
.setUserEmail("test2@openback.com"));
val info = UserInfoExtra()
info.City = "Dublin"
OpenBack.update(OpenBack.Config(applicationContext)
.setExtraUserInfo(info)
.setUserEmail("test2@openback.com"))
info

Available since: 2.0.0

triggerEvent

public static void triggerEvent(Context context, String event, long delay)

Use this API to trigger an event. If a message matches your event and any other triggers, the message will be displayed after the given delay.

Delay is in seconds. If delay is a non-negative number, it will override the default value is set in the OpenBack Dashboard.

Example:

OpenBack.triggerEvent(getApplicationContext(), "MyEvent", 10);
OpenBack.triggerEvent(applicationContext, "MyEvent", 10)
info

Available since: 3.0.0

cancelEvent

public static void cancelEvent(Context context, String event)

Use this API to cancel an event. Removes the displayed and scheduled notifications for the message set to use that event.

Example:

OpenBack.cancelEvent(getApplicationContext(), "MyEvent");
OpenBack.cancelEvent(applicationContext, "MyEvent")
info

Available since: 3.0.6

Config

Config class is used when starting OpenBack. It's a simple container to wrap the initial data passed to the engine.

public Config(Context context)

Instantiate a Config object with the application context.

public Config setOpenBackAppCode(String openBackAppCode)

Set the OpenBack application Code.

This value is generated by the OpenBack Dashboard. If you are using openback.json with the "appCode" field, OpenBack can fill this value automatically so you don't need to call this method. This value is stored internally. If it changes, all the OpenBack data on the device will be erased.

public Config setGcmSenderId(String gcmSenderId)

Set the application GCM/FCM Sender ID.

If you are using gradle and google-services plugin, you don't need to call this method. The GCM/FCM sender ID will be retrieved from the application resources. This value is stored internally. If it changes, a new token will will be requested.

public Config setUserEmail(String email)

Set the user email.

This is optional but if you are using Intelligent Routing with emails, you need to provide a value. This value is stored internally.

public Config setUserMsisdn(String msisdn)

Set the user mobile phone number.

This is optional but if you are using Intelligent Routing with sms, you should to provide a value. If READ_PHONE_STATE is allowed, OpenBack will fill the value. This value is stored internally.

public Config setExtraUserInfo(UserInfoExtra userInfoExtra)

Set user extra info.

note

All the user info values are stored internally.

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

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)
public static void setCustomTrigger(Context context, int triggerIndex, ArrayList<String> value)

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

The ArrayList<String> version is used with the CONTAINS operator on the dashboard.

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

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

getCustomTrigger

@Nullable
public static Object getCustomTrigger(Context context, int triggerIndex)

Get the value associated with a custom trigger. Value can be String, int, float, or ArrayList<String>. For the trigger index, see Custom Triggers list.

Example:

Object value = OpenBack.getCustomTrigger(getApplicationContext(), OpenBack.CUSTOM_TRIGGER_1);
if (value instanceof Integer) {
Integer myint = (Integer)value
}
info

Available since: 3.0.0

UserInfoExtra

Class container for the user info.

NameTypeDescription
AddressLine1StringAddress line 1
AddressLine2StringAddress line 2
AdvertisingIdStringAdvertising identifier set by the application
AgeStringAge
CountryStringCountry
CountryCodeStringISO-2 country code
StateStringState
DateOfBirthStringDate of birth YYYY-MM-DD
FirstNameStringFirst name
GenderStringGender
OptInUpdatesStringOpting in for campaign updates "true"/"false"
PostCodeStringPostal code
ProfessionStringProfession
SurnameStringSurname
TitleStringTitle
CityStringCity
Identity1StringCustom user identifier 1
Identity2StringCustom user identifier 2
Identity3StringCustom user identifier 3
Identity4StringCustom user identifier 4
Identity5StringCustom user identifier 5

Note on Custom User Identifiers:
Identities are 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.

Optional Permissions

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

Payloads

Custom payload content can be added to messages and then used within your app. Payload content can be any form of text (JSON/CSV/XML/HTML), as long as your app can read it.

To read this content in an activity onCreate() and onNewIntent(), you can do a String payload = intent.getStringExtra(OpenBack.OPENBACK_PAYLOAD_EXTRA);

Handling onNewIntent

When using Dynamic 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
}
}