Android API

For integrating a previous version of the SDK, click here.

OpenBack Android SDK version 4+

import com.openback.OpenBack;
  • All fields ands methods are for the OpenBack class.
  • Minimum supported Android level is 19 (android 4.4 aka KitKat).
  • Min Gradle versions; plugin 4.0.1+ / wrapper 6.1.1+

Configuration

setAppCode

Set the OpenBack application code.
You can also provide the app code using the meta-data in your application section:
<meta-data android:name="com.openback.APP_CODE" android:value="YOUR_APP_CODE" />

Definition
public static void setAppCode(@Nullable String appCode)
Example
OpenBack.setAppCode("YOUR_APPCODE");
Parameters
appCodeStringThe OpenBack app code for your application.
Setting the app code with this method will override the meta-data. The app code will be stored. Setting it to null will fallback to the meta-data.

getAppCode

Get the current OpenBack app code used.

Definition
@Nullable
public static String getAppCode()
Example
string appcode = OpenBack.getAppCode();

setAutoStart

Turn on/off the auto-start feature.
You can also enable auto-start feature using the meta-data in your application section:
<meta-data android:name="com.openback.AUTO_START" android:value="true" />

Definition
public static void setAutoStart(boolean autoStart)
Example
OpenBack.setAutoStart(true);
Parameters
autoStartbooleanThe auto-start mode.
Setting the auto-start with this method will override the meta-data.

isAutoStartEnabled

Get the auto-start mode.

Definition
public static boolean isAutoStartEnabled()
Example
bool isEnabled = OpenBack.isAutoStartEnabled();

setGDPRForgetUser

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 compliant, you also need to enable GDPR in your application settings on the OpenBack Dashboard.

Definition
public static void setGDPRForgetUser(boolean gdprForgetUser)
Example
OpenBack.setGDPRForgetUser(true);
Parameters
gdprForgetUserbooleanThe GDPR forget user mode.

isGDPRForgetUserEnabled

Get the GDPR forget user status.

Definition
public static boolean isGDPRForgetUserEnabled()
Example
bool isEnabled = OpenBack.isGDPRForgetUserEnabled();

setCOPPACompliant

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.

Definition
public static void setCOPPACompliant(boolean coppaCompliant)
Example
OpenBack.setCOPPACompliant(true);
Parameters
coppaCompliantbooleanThe COPPA compliant mode.

isCOPPACompliant

Get the COPPA compliant status.

Definition
public static boolean isCOPPACompliant()
Example
bool isEnabled = OpenBack.isCOPPACompliant();

setHIPAACompliant

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

Definition
public static void setHIPAACompliant(boolean hipaaCompliant)
Example
OpenBack.setHIPAACompliant(true);
Parameters
hipaaCompliantbooleanThe HIPAA compliant mode.

isHIPAACompliant

Get the HIPAA compliant status

Definition
public static boolean isHIPAACompliant()
Example
bool isEnabled = OpenBack.isHIPAACompliant();

Runtime

Constants

// The SDK Version
public final static String SDK_VERSION
// Minimum Android level support for this SDK
public final static int ANDROID_MIN_SDK_SUPPORT

start

Start OpenBack.

Definition
public static boolean start()
Example
OpenBack.start();

stop

Stop OpenBack.

Definition
public static boolean stop()
Example
OpenBack.stop();

isStarted

Get the running state of OpenBack.

Definition
public static boolean isStarted()
Example
bool isStarted = OpenBack.isStarted();

resetAll

Reset all the current settings and user data. A new user will be created, and the library will behave as it would on fresh startup (using meta-dat, etc...).

Definition
public static void resetAll()
Example
OpenBack.resetAll();
Example
OpenBack.checkNow();

initialize

Initialize OpenBack with the application context.

This method is called by com.openback.provider.OpenBackInitProvider when the application is launched.

note

You do not need to call this method unless you disable the provider.

Definition
public static void initialize(@NonNull Context context);
Example
OpenBack.initialize(context);
Parameters
contextContextThe application context.

Debug Logs

Constants

public @interface LogLevel {}
public final static int LOG_LEVEL_VERBOSE
public final static int LOG_LEVEL_DEBUG
public final static int LOG_LEVEL_INFO
public final static int LOG_LEVEL_WARN
public final static int LOG_LEVEL_ERROR
public final static int LOG_LEVEL_NONE

setDebugLogLevel

Set the public logging level.

note

Make sure you set the level to LOG_LEVEL_NONE in your release build to avoid leaking information. It can also be achieved with proguard, removing the android.util.log methods.

Definition
public static void setDebugLogLevel(@LogLevel int logLevel);
Example
OpenBack.setDebugLogLevel(OpenBack.LOG_LEVEL_VERBOSE);
Parameters
logLevelLogLevelThe debug log level.

Custom Segments

Constants

public @interface CustomSegmentIndex {}
public final static int CUSTOM_SEGMENT_1
public final static int CUSTOM_SEGMENT_2
public final static int CUSTOM_SEGMENT_3
public final static int CUSTOM_SEGMENT_4
public final static int CUSTOM_SEGMENT_5
public final static int CUSTOM_SEGMENT_6
public final static int CUSTOM_SEGMENT_7
public final static int CUSTOM_SEGMENT_8
public final static int CUSTOM_SEGMENT_9
public final static int CUSTOM_SEGMENT_10

setCustomSegment

Set a custom segment value.

note

Allowed types: String, Long, Double, and List<String>

Definition
public static boolean setCustomSegment(@CustomSegmentIndex int segmentIndex, @Nullable Object value)
Example
OpenBack.setCustomSegment(OpenBack.CUSTOM_SEGMENT_1, "Test");
Parameters
segmentIndexCustomSegmentIndexThe custom segment index.
valueObjectThe custom segment value.

getCustomSegment

Get a custom segment value as an Object.

Definition
public static Object getCustomSegment(@CustomSegmentIndex int segmentIndex)
Example
Object value = OpenBack.getCustomSegment(OpenBack.CUSTOM_SEGMENT_1);
Parameters
segmentIndexCustomSegmentIndexThe custom segment index.

getCustomSegmentAsString

Get a custom segment String value.

Definition
public static String getCustomSegmentAsString(@CustomSegmentIndex int segmentIndex)
Example
String value = OpenBack.getCustomSegmentAsString(OpenBack.CUSTOM_SEGMENT_1);
Parameters
segmentIndexCustomSegmentIndexThe custom segment index.

getCustomSegmentAsLong

public static long getCustomSegmentAsLong(@CustomSegmentIndex int segmentIndex)

Get a custom segment long value.

Definition
public static long getCustomSegmentAsLong(@CustomSegmentIndex int segmentIndex)
Example
long value = OpenBack.getCustomSegmentAsLong(OpenBack.CUSTOM_SEGMENT_1);
Parameters
segmentIndexCustomSegmentIndexThe custom segment index.

getCustomSegmentAsDouble

public static double getCustomSegmentAsDouble(@CustomSegmentIndex int segmentIndex)

Get a custom segment double value.

Definition
public static double getCustomSegmentAsDouble(@CustomSegmentIndex int segmentIndex)
Example
double value = OpenBack.getCustomSegmentAsDouble(OpenBack.CUSTOM_SEGMENT_1);
Parameters
segmentIndexCustomSegmentIndexThe custom segment index.

removeAllCustomSegments

Removes all the custom segments values.

Definition
public static void removeAllCustomSegments()
Example
OpenBack.removeAllCustomSegments();

Attributes

These are a set of pre-defined attributes but you are free to use your own.

public final static String USER_ADDRESS_LINE_1
public final static String USER_ADDRESS_LINE_2
public final static String USER_ADVERTISING_ID
public final static String USER_AGE
public final static String USER_CITY
public final static String USER_COUNTRY
public final static String USER_COUNTRY_CODE
public final static String USER_DATE_OF_BIRTH
public final static String USER_FIRST_NAME
public final static String USER_GENDER
public final static String USER_OPT_IN_UPDATES
public final static String USER_POST_CODE
public final static String USER_PROFESSION
public final static String USER_STATE
public final static String USER_SURNAME
public final static String USER_TITLE
public final static String USER_IDENTITY_1
public final static String USER_IDENTITY_2
public final static String USER_IDENTITY_3
public final static String USER_IDENTITY_4
public final static String USER_IDENTITY_5

setAttribute

Set an attribute Object value.

Definition
public static void setAttribute(@NonNull String attributeKey, @Nullable Object attributeValue)
Example
OpenBack.setAttribute("name", "Bob");
Parameters
attributeKeyStringThe attribute key.
attributeValueObjectThe attribute object value.

setAttributes

Set multiple attributes.

Definition
public static void setAttributes(@NonNull Map<String, Object> attributes)
Example
Map attributes = new HashMap<String, Object>();
attributes.put("name", "Bob");
attributes.put("age", "25");
OpenBack.setAttributes(attributes);
Parameters
attributeKeyStringThe attribute key.
attributeValueMap<String, Object>The attribute map values to add/merge.

getAttribute

Get the attribute for the given key.

Definition
@Nullable
public static Object getAttribute(@NonNull String attributeKey)
Example
Object value = OpenBack.getAttribute("name");
Parameters
attributeKeyStringThe attribute key.

getAttributeAsString

Get the attribute as String for the given key.

Definition
@Nullable
public static String getAttributeAsString(@NonNull String attributeKey)
Example
String value = OpenBack.getAttributeAsString("name");
Parameters
attributeKeyStringThe attribute key.

getAttributeAsLong

Get the attribute as long for the given key.

Definition
@Nullable
public static long getAttributeAsLong(@NonNull String attributeKey)
Example
long value = OpenBack.getAttributeAsLong("name");
Parameters
attributeKeyStringThe attribute key.

getAttributeAsDouble

Get the attribute as double for the given key.

Definition
@Nullable
public static double getAttributeAsDouble(@NonNull String attributeKey)
Example
double value = OpenBack.getAttributeAsDouble("name");
Parameters
attributeKeyStringThe attribute key.

getAllAttributes

Get all the attributes

Definition
public static Map<String, Object> getAllAttributes()
Example
Map attributes = new HashMap<String, Object>();
attributes = OpenBack.getAllAttributes();

removeAllAttributes

Removes all the attributes.

Definition
public static void removeAllAttributes()
Example
OpenBack.removeAllAttributes();

Logging Goals

logGoal

Log a goal achieved.

Definition
public static boolean logGoal(@NonNull String goal, int step, double value)
public static boolean logGoal(@NonNull String goal, int step, double value, @Nullable String currency)
Example
OpenBack.logGoal("goalCode", 1, 10.0);
OpenBack.logGoal("goalCode", 1, 10.0, "USD");
Parameters
goalStringThe achieved goal.
stepintThe goal step number.
valuedoubleThe value associated with the goal step.
currencyStringThe currency code (ISO 4217)

Signal Event

// Default delay value set in the OpenBack Dashboard (-1)
public static final long EVENT_DELAY_MESSAGE_DEFAULT

signalEvent

Signal an event.

Messages using the event signal that match the event name will be displayed after the given delay (seconds). To use the default delay value set in the OpenBack Dashboard, use EVENT_DELAY_MESSAGE_DEFAULT.

note

Any non-negative number will override the default value set in the OpenBack Dashboard.

Definition
public static void signalEvent(@NonNull String event, long delay)
Example
OpenBack.signalEvent("event", 10);
Parameters
eventStringThe event signal.
delaylongThe delay to wait before displaying the messages in seconds.

cancelEvent

Cancel an event.

Definition
public static void cancelEvent(@NonNull String event)
Example
OpenBack.cancelEvent("event");
Parameters
eventStringThe event to cancel.
tip

If you already have a class for tracking events, you can also call OpenBack at the same time.

Topics

getSubscribedTopics

Get the list of subscribed topics.

Definition
public static List<String> getSubscribedTopics()
Example
List<String> topics = OpenBack.getSubscribedTopics();

isSubscribedToTopic

Check if the user is subscribed to a certain topic.

Definition
public static boolean isSubscribedToTopic(@NonNull String topic)
Example
bool isSubscribed = OpenBack.isSubscribedToTopic("ABCXYZ");
Parameters
topicStringThe topic code.

subscribeToTopic

Subscribe to a topic.

Definition
public static boolean subscribeToTopic(@NonNull String topic)
Example
OpenBack.subscribeToTopic("ABCXYZ");
Parameters
topicStringThe topic code.

subscribeToTopics

Subscribe to multiple topics.

Definition
public static boolean subscribeToTopics(@NonNull List<String> topics)
Example
List<String> topics = new ArrayList<>();
topics.add("topic1");
topics.add("topic2");
OpenBack.subscribeToTopics(topics);
Parameters
topicsList<String>The list of topic codes.

unsubscribeFromTopic

Unsubscribe from a topic.

Definition
public static boolean unsubscribeFromTopic(@NonNull String topic)
Example
OpenBack.unsubscribeFromTopic("topic1");
Parameters
topicStringThe topic code.

unsubscribeFromTopics

Unsubscribe from multiple topics.

Definition
public static boolean unsubscribeFromTopics(@NonNull List<String> topics)
Example
List<String> topics = new ArrayList<>();
topics.add("topic1");
topics.add("topic2");
OpenBack.unsubscribeFromTopics(topics);
Parameters
topicList<String>The list of topic codes.

unsubscribeFromAllTopics

Unsubscribe from all topics.

Definition
public static boolean unsubscribeFromAllTopics()
Example
OpenBack.unsubscribeFromAllTopics();

App Inbox

note

It is highly recommended to call the App Inbox API from a background thread as calls are blocking.

getAppInboxMessageCount

Get the total number of inbox messages.

Definition
public static long getAppInboxMessageCount()
Example
long messageCount = OpenBack.getAppInboxMessageCount();

getAppInboxUnreadMessageCount

Get the number of unread inbox messages.

Definition
public static long getAppInboxUnreadMessageCount()
Example
long messageCount = OpenBack.getAppInboxUnreadMessageCount();

getAppInboxMessages

Get all the inbox messages.

Definition
@NonNull
public static List<AppInboxMessage> getAppInboxMessages()
Example
List<AppInboxMessage> inboxMessages = OpenBack.getAppInboxMessages();

getAppInboxReadMessages

Get all the read inbox messages.

Definition
@NonNull
public static List<AppInboxMessage> getAppInboxReadMessages()
Example
List<AppInboxMessage> readInboxMessages = OpenBack.getAppInboxReadMessages();

getAppInboxUnreadMessages

Get all the unread inbox messages.

Definition
@NonNull
public static List<AppInboxMessage> getAppInboxUnreadMessages()
Example
List<AppInboxMessage> unreadInboxMessages = OpenBack.getAppInboxUnreadMessages();

markAppInboxMessageAsRead

Mark an inbox message as read.

Definition
public static boolean markAppInboxMessageAsRead(@NonNull AppInboxMessage inboxMessage)
Example
OpenBack.markAppInboxMessageAsRead(inboxMessages.get(0));
Parameters
inboxMessageAppInboxMessageThe app inbox message.

markAppInboxMessagesAsRead

Mark multiple inbox messages as read.

Definition
public static boolean markAppInboxMessagesAsRead(@NonNull List<AppInboxMessage> inboxMessages)
Example
List<AppInboxMessage> inboxMessages = OpenBack.getAppInboxMessages();
OpenBack.markAppInboxMessagesAsRead(inboxMessages);
Parameters
inboxMessagesList<AppInboxMessage>The list of app inbox messages.

markAllAppInboxMessagesAsRead

Mark all the inbox messages as read.

Definition
public static boolean markAllAppInboxMessagesAsRead()
Example
OpenBack.markAllAppInboxMessagesAsRead();

removeAppInboxMessage

Remove an inbox message.

Definition
public static boolean removeAppInboxMessage(@NonNull AppInboxMessage inboxMessage)
Example
OpenBack.removeAppInboxMessage(inboxMessages.get(0));
Parameters
inboxMessageAppInboxMessageThe app inbox message.

removeAppInboxMessages

Remove multiple inbox messages.

Definition
public static boolean removeAppInboxMessages(@NonNull List<AppInboxMessage> inboxMessages)
Example
List<AppInboxMessage> inboxMessages = OpenBack.getAppInboxMessages();
OpenBack.removeAppInboxMessages(inboxMessages);
Parameters
inboxMessagesList<AppInboxMessage>The list app inbox messages.

removeAllAppInboxMessages

Remove all the inbox messages.

Definition
public static boolean removeAllAppInboxMessages()
Example
OpenBack.removeAllAppInboxMessages();

executeAppInboxMessage

Execute the inbox message if actionable

Definition
public static boolean executeAppInboxMessage(@NonNull AppInboxMessage inboxMessage)
Example
OpenBack.executeAppInboxMessage(inboxMessages.get(0));
Parameters
inboxMessageAppInboxMessageThe app inbox message.

AppInboxMessage Class

public final class AppInboxMessage {
public String title; // Message title
public String content; // Message content
public String payload; // Message payload
public String thumbnail; // Message thumbnail path
public long displayTime; // Display time in epoch seconds
public long expirationTime; // Expiration time in epoch seconds
public boolean read; // Message read state
public boolean actionable; // Message can be executed if true
}

Firebase Messaging Handler

handleFcmMessage

note

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

Definition
public static boolean handleFcmMessage(@NonNull Map<String, String> data)
Example
public void onMessageReceived(RemoteMessage remoteMessage) {
if (!OpenBack.handleFcmMessage(remoteMessage.getData())) {
// FCM Message was not handled by OpenBack
Log.e("FIREBASE", "Not an OpenBack message");
}
}
Parameters
dataMap<String, String>The data content of the Firebase message.

refreshFcmToken

public static void refreshFcmToken(@NonNull String token)
note

If your application already uses FCM message service class, call this method to update the device token.

Definition
public static void refreshFcmToken(@NonNull String token)
Example
OpenBack.refreshFcmToken("yourToken");
Parameters
tokenStringThe new Firebase token.

Developer Tools

checkMessagesNow

Run the message checker.

Definition
public static void checkMessagesNow()

reloadMessagesNow

Reload the messages now

Definition
public static void reloadMessagesNow()

areMessagesLoaded

Check if messages have been loaded on the device.

Definition
public static boolean areMessagesLoaded()