Unity

Integration Guide

The OpenBack Unity plugin provides the API interface to the native OpenBack Android and iOS SDKs. We recommend using the External Dependency Manager for Unity to import the SDKs and their dependencies. It provides a simple way to get the OpenBack SDKs from our maven repository and Cocoapods.

The plugin source code is available on GitHub as part of the Sample app.

note

The OpenBack Unity SDK is built using Unity version 2019.4.16f1.

Import OpenBack Unity plugin

Download one of the 2 packages:

• OpenBackWithResolver.unitypackage: OpenBack Unity plugin + External Dependency Manager for Unity.
• OpenBack.unitypackage: OpenBack Unity plugin.

To import the package, double click the package with your Unity project open or use the menu Assets > Import Package > Custom Package..

note

• The current OpenBack dependencies are listed in OpenBackDependencies.xml.
• The version of the packaged External Dependency Manager for Unity is v1.2.162.

Use the OpenBack package if you don't want to use External Dependency Manager. You will need to follow the native integration guides for Android and iOS. Configuration can still be done from the Unity editor window.

Configure OpenBack

After importing the OpenBack Unity package, open the configuration window from the menu Window > OpenBack > Settings

   

iOS Configuration

For more detailed information on advanced settings, check the the full iOS documentation.

Editor Settings

Setting	Overview
App Code	The OpenBack app code for your application
App Group	The app group used for OpenBack and app extenstions
Log Level	The debug log level (None to Verbose)
Clear Badge Count	Controls if OpenBack clears the badge number when the app is opened
LargeIcon	Default large icon for notification (filename in main bundle or image asset name)
Sound	Set the default notification sound (filename in main bundle)
Auto Start	Controls if OpenBack starts automatically.
Enable Core Motion	Controls if library can use Core Motion Activity manager.
Enable Microphone	Controls if OpenBack can use the microphone.
Enable Proximity	Controls if OpenBack can use the proximity sensor.
Use Swizzling	Controls if swizzling is enabled. If you disable swizzling, you must hook some delegate calls to OpenBack (see docs).

Enabling Push Notifications

Open the Xcode workspace generated by the build and enable push notifications in the project capabilities. See the Setup APNs Certificates for Push Notifications guide for more info.

Optional Frameworks

If you are planning to use location, core motion or bluetooth signals, you need to add the OpenBack optional modules to your dependencies in the Cocoapod section of OpenBack/Editor/OpenBackDependencies.xml. Check the iOS Signals docs for more info.

<!-- iOS Cocoapod dependencies -->

<iosPods>

...

<iosPod name="OpenBackLocation" bitcodeEnabled="true" minTargetSdk="10.0">

<sources>

<source>https://github.com/CocoaPods/Specs</source>

</sources>

</iosPod>

....

</iosPods>

Android Configuration

For more detailed information on advanced settings, check the the full Android documentation.

For a quick walkthrough of the integration, you can watch our tutorial video below.

Configuration

After importing the OpenBack package and adding your App Code, open the Plugins > Android > OpenBackUnity folder. This folder should contain two files:

• AndroidManifest.xml
• project.properties

The AndroidManifest.xml will contain your App Code and any other settings that you save in the editor window, the project.properties file should contain the two lines below.

target=android-19

android.library=true

Editor Settings

Setting	Overview
App Code	The OpenBack app code for your application
Log Level	The debug log level (None to Verbose)
Icon	The resource ID for the notification icon (e.g. @drawable/xxx).
Color Accent	The resource ID for the notification color accent (e.g. @color/xxx).
Large Icon	The resource ID for the notification large icon (e.g. @drawable/xxx).
Sound	The resource ID for the notification sound in res/raw (e.g. @raw/xxx).
Channel	The string name of the default notification channel (e.g. @string/xxx or direct value).
Channel Description	The string description of the default notification channel (e.g. @string/xxx or direct value)
Auto Start	Controls if OpenBack automatically starts.

Adding Resources

Go to your project Assets > Plugins > Android > OpenBackUnity and add a res folder with the assets.

Notification Icon

To set the notification icon used by OpenBack, generate the icon image files (from Android Studio or Android Asset Studio) and place the result in res folder. Then set the Icon field in the editor to the resource name @drawable/ic_notification_icon.

Firebase Setup

Add the OpenBack Firebase service handlers in your Android manifest. See Setting Up Firebase for more details.

When using the resolver, the Firebase dependency is included in OpenBack/Editor/OpenBackDependencies.xml. You need to copy the google-services.json file from your Firebase console. See Setting Up Firebase for more details.

You can also use the Firebase SDK for Unity. Download the Firebase SDK and import FirebaseMessaging.unitypackage in your project. Follow the Setup for Android steps.

note

We recommend using FCM but it is not required. If you do not want to use FCM, just comment out the dependency in OpenBack/Editor/OpenBackDependencies.xml.

Location Services

If you plan on using the Location signal, uncomment the section in the OpenBack dependencies OpenBack/Editor/OpenBackDependencies.xml. You will need to run the resolver again.

API Documentation

Use these endpoints to interact with OpenBack SDK.

The API is defined in the OpenBackUnity namespace and is accessed using the OpenBack.SharedInstance object of the OpenBack class.

Check the SampleApp for some sample usage.

Configuration

// Log Levels

public enum OpenBackLogLevel {

None = 0, Error = 1, Warning = 2, Info = 3, Debug = 4, Verbose = 5

};

// Get and Set the app code

string AppCode { get; set; }

// Enable or disable auto start

bool AutoStart { get; set; }

// Enable or disable forget user status

bool GdprForgetUser { get; set; }

// Enable or disable Coppa compliant status

bool CoppaCompliant { get; set; }

// Enable or disable Hipaa compliant status

bool HipaaCompliant { get; set; }

// Get and Set the debug log level

OpenBackLogLevel DebugLogLevel { get; set; }

// Get the current native SDK version

string SdkVersion { get; }

Runtime

// Start OpenBack

bool Start();

// Stop OpenBack - Note: OpenBack will not restart until Start() is called even if AutoStart is true.

void Stop();

// Returns true if OpenBack is running

bool Started { get; }

// Reset all the settings and data

void ResetAll();

Custom Segments

// The accessible custom segments

public enum OpenBackSegment {

CustomSegment1 = 0, CustomSegment2 = 1, CustomSegment3 = 2, CustomSegment4 = 3, CustomSegment5 = 4,

CustomSegment6 = 5, CustomSegment7 = 6, CustomSegment8 = 7, CustomSegment9 = 8, CustomSegment10 = 9

};

// Set a long value to a custom segment

void SetCustomSegment(OpenBackSegment segment, long value);

// Set a doube value to a custom segment

void SetCustomSegment(OpenBackSegment segment, double value);

// Set a string value to a custom segment

void SetCustomSegment(OpenBackSegment segment, string value);

// Get a long value from a custom segment

long GetCustomSegmentAsLong(OpenBackSegment segment);

// Get a doube value from a custom segment

double GetCustomSegmentAsDouble(OpenBackSegment segment);

// Get a string value from a custom segment

string GetCustomSegmentAsString(OpenBackSegment segment);

// Clear all custom segments

void RemoveAllCustomSegments();

Attributes

// Set a long value to an attribute

void SetAttribute(string attributeKey, long attributeValue);

// Set a double value to an attribute

void SetAttribute(string attributeKey, double attributeValue);

// Set a string value to an attribute

void SetAttribute(string attributeKey, string attributeValue);

// Get a long value for an attribute

long GetAttributeAsLong(string attributeKey);

// Get a double value for an attribute

double GetAttributeAsDouble(string attributeKey);

// Get a string value for an attribute

string GetAttributeAsString(string attributeKey);

// Clear all the attributes

void RemoveAllAttributes();

// List of Pre-Defined attribute keys

public const string UserAddressLine1 = "addressLine1";

public const string UserAddressLine2 = "addressLine2";

public const string UserAdvertisingId = "advertisingId";

public const string UserAge = "age";

public const string UserCity = "city";

public const string UserCountry = "country";

public const string UserCountryCode = "countryCode";

public const string UserDateOfBirth = "dateOfBirth";

public const string UserEmailAddress = "emailAddress";

public const string UserFirstName = "firstName";

public const string UserGender = "gender";

public const string UserOptInUpdates = "optInUpdates";

public const string UserPhoneNumber = "phoneNumber";

public const string UserPostCode = "postCode";

public const string UserProfession = "profession";

public const string UserState = "state";

public const string UserSurname = "surname";

public const string UserTitle = "title";

public const string UserIdentity1 = "identity1";

public const string UserIdentity2 = "identity2";

public const string UserIdentity3 = "identity3";

public const string UserIdentity4 = "identity4";

public const string UserIdentity5 = "identity5";

Goals

// Log a goal

void LogGoal(string goal, int step, double value, string currency = null);

Event Signal

// Signal an event with a delay in seconds

void SignalEvent(string theEvent, long delay);

// Cancel an event

void CancelEvent(string theEvent);

Developer Tools

// Run the message checker

void CheckMessagesNow();

// Reload the messages now

void ReloadMessagesNow();

A/B Testing

You can use Custom Segments to create different user groups for A/B testing. When you initialize the SDK, you can randomly assign each user to a different numbered group and then you can specifically target this group when A/B testing. You can use the example code below to quickly assign a user to a random group.

// generate a random number

openBack.SetCustomSegment(OpenBackSegment.CustomSegment1, Random.Range(1, 4));