React Native

React

React Native lets you build mobile apps using only JavaScript. It uses the same design as React, letting you compose a rich mobile UI from declarative components.

OpenBack React Native Module

The OpenBack React Native module makes it possible for your React Native application to interact with the OpenBack library. The module is avilable for iOS and Android.

info

A sample application is available on Github here. The module source code is available on Github here.

Getting started

Install the module in your package:

npm install react-native-openback --save

Link the native module to your iOS and Android applications:

react-native link react-native-openback

Before building the application, some minimal platform specific integration steps are needed.

iOS Integration

Create a Cocoapods Podfile in the /ios with pod init, then edit the Podfile adding pod OpenBack as well as enabling the dynamic framework feature use_frameworks!. Install OpenBack using pod update.

Follow the iOS Integration Documentation to fully configure OpenBack.

For best results, make sure to configure and start OpenBack from the application delegate didFinishLaunchingWithOptions:.

Android Integration

Edit the application /android/app/build.gradle to include the OpenBack library repository location and dependency.

repositories {
maven { url 'https://maven.openback.com/public' }
}
dependencies {
...
implementation "com.openback:OpenBack:2.+"
}
note

OpenBack library uses a few android support libraries at version 28. You might need to use the gradle resolutionStrategy if you want to use lower versions.

Follow the Android Integration Documentation to fully configure OpenBack.

For best results, make sure to configure and start OpenBack from the main application OnCreate() call.

API

The OpenBack React Native library contains 2 modules:

  • OpenBack (alias for RNOpenBack in NativeModules)
  • OpenBackAppInbox (alias for RNOpenBackppInbox in NativeModules)

To import OpenBack modules in your javascript application, use the following:

import { OpenBack, OpenBackAppInbox } from 'react-native-openback'

coppaCompliant

coppaCompliant(bool compliant)

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

Example:

OpenBack.coppaCompliant(true);

gdprForgetUser

gdprForgetUser(bool 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(true);

sdkVersion

sdkVersion(Callback callback)

Returns the current OpenBack SDK version.

Example:

OpenBack.sdkVersion((error, version) => {
...
}

Logging a Goal

Definition
logGoal(string goal, int step, double value, Callback callback)

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

Example
OpenBack.logGoal("Test", 1, 12.3, (error) => { });

User Info & Custom Values

setCustomTrigger

setCustomTriggerString(int trigger, string value, Callback callback)
setCustomTriggerInteger(int trigger, int value, Callback callback)
setCustomTriggerFloat(int trigger, float value, Callback callback)

Set a custom trigger value. Value can be string, integer or float.
For the trigger index, use kOBKCustomTrigger1 to kOBKCustomTrigger10.

Example:

OpenBack.setCustomTriggerString(OpenBack.kOBKCustomTrigger1, "customString", (error) => {});
OpenBack.setCustomTriggerInteger(OpenBack.kOBKCustomTrigger2, 123, (error) => {});
OpenBack.setCustomTriggerFloat(OpenBack.kOBKCustomTrigger3, 2.56, (error) => {});

setUserInfo

setUserInfo(object, Callback callback)

The application can pass some extra user information using a simple dictionary object by setting the following fields:

NameTypeDescription
addressLine1stringAddress line 1
addressLine2stringAddress line 2
advertisingIdstringAdvertising identifier set by the application
agestringAge
citystringCity
countrystringCountry
countryCodestringISO-2 country code
dateOfBirthstringDate of birth YYYY-MM-DD
emailAddressstringEmail Address
firstNamestringFirst name
genderstringGender
optInUpdatesstringOpting in for message updates "true"/"false"
phoneNumberstringPhone Number (international format)
postCodestringPostal code
professionstringProfession
statestringState
surnamestringSurname
titlestringTitle
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

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

Example:

OpenBack.setUserInfo({
'firstName': 'John',
'surname': 'Doe',
'emailAddress': 'john@doe.com'
}, (error) => {});

App Inbox API

App Inbox is available on iOS since version 1.8.7 and Android since version 2.4.6.

Inbox Messages

App Inbox messages are simple javascript objects with the following keys:

NameTypeDescription
readbooleantrue if message is marked as read
actionablebooleantrue if message is actionable (see executeMessage)
deliveryTimeintegerunix epoch time when the message was delivered
titlestringtitle of the message
contentstringcontent of the message
payloadstringpayload of the message
warning

Do not modify actionable, deliveryTime or _id when passing a message back to the API to remove, mark as read or execute it. Those values are used to retrieve the message on the native library side.

getMessageCount

async getMessageCount()

Total number of messages in inbox.

Example:

var count = await OpenBackAppInbox.getMessageCount()

getUnreadMessageCount

async getUnreadMessageCount()

Total number of unread messages in inbox.

Example:

var count = await OpenBackAppInbox.getUnreadMessageCount()

getAllMessages

async getAllMessages()

Retrieve all Inbox messages. Messages are sorted by display time, from newest to oldest.

Example:

var messages = await OpenBackAppInbox.getAllMessages();

getReadMessages

async getReadMessages()

Retrieve all Inbox read messages. Messages are sorted by display time, from newest to oldest.

Example:

var messages = await OpenBackAppInbox.getReadMessages();

getUnreadMessages

async getUnreadMessages()

Retrieve all Inbox unread messages. Messages are sorted by display time, from newest to oldest.

Example:

var messages = await OpenBackAppInbox.getUnreadMessages();

markMessageAsRead

async markMessageAsRead(message)

Mark an Inbox message as read. Returns true if successful.

Example:

await OpenBackAppInbox.markMessageAsRead(message);

markMessagesAsRead

async markMessagesAsRead(messages)

Mark Inbox messages as read. Returns true if successful.

Example:

await OpenBackAppInbox.markMessagesAsRead(messages);

markAllMessagesAsRead

async markAllMessagesAsRead()

Mark all Inbox messages as read. Returns true if successful.

Example:

await OpenBackAppInbox.markAllMessagesAsRead();

removeMessage

async removeMessage(message)

Remove message from the Inbox. Returns true if successful.

Example:

await OpenBackAppInbox.removeMessage(message);

removeMessages

async removeMessages(messages)

Remove messages from the Inbox. Returns true if successful.

Example:

await OpenBackAppInbox.removeMessages(messages);

removeAllMessages

async removeAllMessages()

Remove all message from the Inbox. Returns true if successful.

Example:

aait OpenBackAppInbox.removeAllMessages();

executeMessage

async executeMessage(message)

If a message is actionable, call this method to execute the associated action. Messages can have an actionable URL, deep-link, video, image, custom HTML. Executing a message will set the read status to true. Returns true if successful.

Example:

await OpenBackAppInbox.executeMessage(message);

Listen for App Inbox Changes

Create a NativeEventEmitter from the OpenBackInbox and add listener for the following events:

  • OBKAppInboxMessageAdded: A message was added
  • OBKAppInboxMessageRead: A message was read
  • OBKAppInboxMessageExpired: A message has expired
note

Currently, only iOS passes the message linked to the event. It will be added to Android in the future.

Example:

this.openBackAppInboxEmitter = new NativeEventEmitter(OpenBackAppInbox);
this.openBackAppInboxEmitter.addListener('OBKAppInboxMessageAdded', (message) => {
console.log('Message added: ' + JSON.stringify(message));
// Refresh message list...
});
this.openBackAppInboxEmitter.addListener('OBKAppInboxMessageRead', (message) => {
console.log('Message read: ' + JSON.stringify(message));
// Refresh message list...
});
this.openBackAppInboxEmitter.addListener('OBKAppInboxMessageExpired', (message) => {
console.log('Message expired: ' + JSON.stringify(message));
// Refresh message list...
});