Skip to main content

Unity

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:

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

note

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

Unity Menu   OpenBack Unity Editor

iOS Configuration

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

Editor Settings

SettingOverview
App CodeThe OpenBack app code for your application
App GroupThe app group used for OpenBack and app extenstions
Log LevelThe debug log level (None to Verbose)
Clear Badge CountControls if OpenBack clears the badge number when the app is opened
LargeIconDefault large icon for notification (filename in main bundle or image asset name)
SoundSet the default notification sound (filename in main bundle)
Auto StartControls if OpenBack starts automatically.
Enable Core MotionControls if library can use Core Motion Activity manager.
Enable MicrophoneControls if OpenBack can use the microphone.
Enable ProximityControls if OpenBack can use the proximity sensor.
Use SwizzlingControls 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.

Xcode Push Notifications

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

SettingOverview
App CodeThe OpenBack app code for your application
Log LevelThe debug log level (None to Verbose)
IconThe resource ID for the notification icon (e.g. @drawable/xxx).
Color AccentThe resource ID for the notification color accent (e.g. @color/xxx).
Large IconThe resource ID for the notification large icon (e.g. @drawable/xxx).
SoundThe resource ID for the notification sound in res/raw (e.g. @raw/xxx).
ChannelThe string name of the default notification channel (e.g. @string/xxx or direct value).
Channel DescriptionThe string description of the default notification channel (e.g. @string/xxx or direct value)
Auto StartControls if OpenBack automatically starts.

Adding Resources

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

OpenBack Unity Project

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