Upsight logo Back to top

Enterprise Unity

Quick Start Guide

The Basics


Before You Start

The Upsight Enterprise Unity Plugin is built as a wrapper for the Upsight Enterprise Android SDK and Upsight Enterprise iOS SDK.

Using the plugin, instead of their native counterparts, allows you to interface with each SDK with C# method calls from the KontagentBinding object. When integrating the Enterprise Unity Plugin, you will need to download and import the packages for the platform you are targeting (i.e. iOS if your app is targeting iOS devices, Android if your app is targeting Android devices, both if your app is targeting both). You do not need to download the Enterprise SDKs separately as well, since each one is packaged in its respective plugin.

The Upsight Enterprise Unity SDK currently supports the following versions:

  • Android: API Level 10+.
  • iOS: The Upsight Enterprise iOS SDK currently supports iOS 6+ and armv7 iOS devices.

Older devices, (such as iPad 1, iPhone 3g, and the original iPhone, and older versions of Android, for example) are not supported.

Step 1 Import the Plugin

Download the Upsight Enterprise Unity Plugin for the desired platform. The latest version is available here.

Note You do not need to download the SDK files, but if your app is to run on both Android and iOS, download both the Android and iOS Unity Plugins.

Extract the archives and then import their contents into your Unity project by clicking Assets > Import Package > Custom Package.

Important If you are building an app for both Android and iOS, remember to import both Android and iOS plugins.

Import Custom Package

Note If you are building an app for iOS, you will need to remove the following files:

  • If you are using IDFA, you will need to delete

    • libKontagent_MOBAQ.a

    • libKontagent_FB.a

  • If you are not using IDFA, you will need to delete

    • libKontagent_MOBACQ_IDFA.a

    • libKontagent_FB.a

The app will not build with both libKontagent_MOBACQ_IDFA.a and libKontagent_MOBAQ.a.

Step 2 Initialize the Plugin

Use the KontagentBinding object's method calls to work with the plugin. Whenever you want to send messages to the server, you must first initialize the plugin by calling the KontagentBinding.startSession method in your own script. You will not be able to send other messages without starting a session.

Note After initializing the plugin, you must run the scene on a physical device. You cannot test Upsight functionality from the Unity editor.

The sample code below shows how to call the KontagentBinding.startSession method. The script would need to be attached to a GameObject in your Unity project. This sample script has three variables and two method calls to make note of.

  1. apiKey is a string currently set to a random set of characters. If you are releasing this Unity app to Android, this variable should be set to the Android API Key for your app's QA application. If you are releasing this Unity app to iOS, this variable should be set to the iOS API Key for your app's QA application. This can be found on the Upsight Analytics Dashboard.
  2. isTestMode is a boolean currently set to true. During the instrumentation phase, this should remain set to true. More information in the Test Your Instrumentation section below.
  3. KontagentBinding.startSession method is called in the Start method so that it can be called at app launch. It is also called in the OnApplicationPause method if the pauseStatus parameter is false so that it is called every time your app is opened after being backgrounded.
  4. KontagentBinding.stopSession is called in the OnApplicationPause method if the pauseStatus parameter is true so that your session will stop every time your app is backgrounded. More information in the Stop Session section below.
    public class MyUpsightAdapter : MonoBehaviour {
    
    #if UNITY_ANDROID
        string apiKey = "YOUR_QA_ANDROID_API_KEY_GOES_HERE";
    #else
        string apiKey = "YOUR_QA_IOS_API_KEY_GOES_HERE";
    #endif
    
        bool isTestMode = true;
    
        void Start () {
    
            KontagentBinding.startSession(apiKey, isTestMode);
    
        }
    
        void OnApplicationPause (bool pauseStatus) {
    
            if (pauseStatus) {
                KontagentBinding.stopSession();
            } else {
                KontagentBinding.startSession(apiKey, isTestMode);
            }
    
        }
    
    }
    

Important If you are using the Enterprise and regular SDKs, make sure to call the startSession method before making an requestAppOpen Open Call.

Android Specific Configurations

If you are building an app for Android, you will need to add the following permissions to your AndroidManifest.xml file.

  • android.permission.INTERNET
  • android.permission.ACCESS_WIFI_STATE
  • android.permission.ACCESS_NETWORK_STATE

This is what it would look like in the Android Manifest file:

<manifest xmlns:android...>
    ...
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    ...
</manifest>

iOS Specific Configurations

If you are building an app for iOS, you will need to add AdSupport.framework to your Link Binary With Libraries list.

Under Build Phases, expand Link Binary With Libraries. At the bottom of the list, click the + (plus) button. Locate the AdSupport.framework framework and click Add.

AdSupport Framework

Step 3 Test Your Instrumentation

During the instrumentation phase, direct your application to send data to our Test Server. To send data to the Test Server, point all API calls to the Test Server in the KontagentBinding.startSession method using the boolean enableTestMode parameter.

bool isTestMode = true;

// ...

KontagentBinding.startSession(apiKey, isTestMode);

You can now view your data by clicking your QA App in the Test Server, in the Developer Tools, in the Upsight Analytics Dashboard.

Step 4 View and QA Your Test Data

Once you have validated your instrumentation with our Test Server and would like to view your test data, you must send this data to our Production Server. Change enableTestMode in the KontagentBinding.startSession method to send data to the Production Server:

bool isTestMode = false;

//...

KontagentBinding.startSession(apiKey, isTestMode);

You can now view your data by clicking your QA App in the Upsight Analytics Dashboard.

Once data is sent, you can also run integration reports and receive immediate feedback on the validity of your instrumentation. For example, the Integration Reports tool can be used to generate a QA of your API calls. Using these tools to validate your instrumentation will help ensure data integrity when data is sent to our production servers.

Important You should be using your QA API key when testing your non-production instrumentation.

Step 5 Send Your Production Data to Upsight Analytics

During the testing of your instrumentation, you should have been using your QA application (MyApp - QA). When you are ready to send data to our production servers to view in your production application instance (MyApp - Production), simply change the API Key you are passing to the KontagentBinding.startSession to point to the Production Server and production application:

#if UNITY_ANDROID
    string apiKey = "YOUR_PRODUCTION_ANDROID_API_KEY_GOES_HERE";
#else
    string apiKey = "YOUR_PRODUCTION_IOS_API_KEY_GOES_HERE";
#endif

bool isTestMode = false;

//...

void Start () {

    KontagentBinding.startSession(apiKey, isTestMode);

}

From this point on, you are live, and Upsight will update your data on an hourly basis. To view your production data, click on your Production App in the Upsight Analytics Dashboard.

As the Android SDK is built on top of our Data Collection API, all required and optional parameters, as well as any constraints, are synonymous with the Data Collection API specification.

Quick Start Guide

Important Methods


Capturing Device Information

After the KontagentBinding.startSession call, you should immediately send the KontagentBinding.sendDeviceInformation call.

Dictionary<string, string> optionalParams = new Dictionary<string, string>();

optionalParams.Add("v_maj", "1.2.3");

KontagentBinding.sendDeviceInformation(optionalParams);

Refer to the Basic Enterprise Unity Methods and Advanced Enterprise Unity Methods sections below for more information and code examples.

Stop Session

When you call the KontagentBinding.startSession method, you begin a session with the Upsight servers. You typically want to end a session when the app closes, and when the app is backgrounded. The following example shows how to pause a session when your application is backgrounded, and start up a session again when it is returned from the background.

void OnApplicationPause (bool pauseStatus) {

    if (pauseStatus) {
        KontagentBinding.stopSession();
    } else {
        KontagentBinding.startSession(apiKey, isTestMode);
    }

}

This will help isolate when your user is using your app, and also prevent the app from sending data to the Upsight servers when it's not in use.

SDK Logging

If you would like to enable/disable SDK logging, include the appropriate line of code. The default setting is disabled.

Enabling Debugging:

KontagentBinding.enableDebug();

Disabling Debugging:

KontagentBinding.disableDebug();

Basic Messages

startSession


Overview

Call this method to initiate the SDK. An apa message will be sent on first run.

Note The Enterprise SDK creates a user identifier, referred to as the sender ID. This ID can be substituted with another identifier (i.e. Your own ID). When substituting with another identifier, ensure that it is an integer, otherwise it will not pass.

Warning Using a custom sender ID instead of the one generated by the SDK can result in potential drawbacks for marketing and analytics. For further information, please contact your CSM or Upsight Support.

Overload List

Method CallParameters
void startSession(
        string apiKey, 
        bool enableTestMode )
  • apiKey
  • enableTestMode
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId )
  • apiKey
  • enableTestMode
  • senderId
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId,
        bool shouldSendAPA )
  • apiKey
  • enableTestMode
  • senderId
  • shouldSendAPA
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId,
        string fbAppID )
Depricated
  • apiKey
  • enableTestMode
  • senderId
  • fbAppID
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId,
        bool shouldSendAPA,
        string apiKeyForTimezone,
        string apiKeyTimezoneOffset,
        string customID )
Depricated
  • apiKey
  • enableTestMode
  • senderId
  • shouldSendAPA
  • apiKeyForTimezone
  • apiKeyTimezoneOffset
  • customID
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId,
        bool shouldSendAPA,
        string apiKeyForTimezone,
        string apiKeyTimezoneOffset,
        string customID,
        string fbAppID )
Depricated
  • apiKey
  • enableTestMode
  • senderId
  • shouldSendAPA
  • apiKeyForTimezone
  • apiKeyTimezoneOffset
  • customID
  • fbAppID
void startSession(
        string apiKey,
        bool enableTestMode,
        string senderId,
        bool shouldSendAPA,
        string apiKeyForTimezone,
        string apiKeyTimezoneOffset,
        string customID,
        string fbAppID,
        bool enableAcquisitionTracking )
  • apiKey
  • enableTestMode
  • senderId
  • shouldSendAPA
  • apiKeyForTimezone
  • apiKeyTimezoneOffset
  • customID
  • fbAppID
  • enableAcquisitionTracking

Parameters

ParameterTypeDescription
apiKeystringThe API Key of your application. This key is automatically generated when you set up your application in your Dashboard.
enableTestModebooleanDetermines whether you send data to Upsight Analytics Test or Production servers. For Production, set this parameter to false. For Test, set this parameter to true. Default is false.
senderIdstringA unique, unsigned 64-bit integer in the form of a String. This parameter denotes the unique identifier of the application user. If your application creates user IDs larger than 64-bits, you must convert the user ID to an unsigned 64-bit integer to send to Upsight Analytics. For more information click here.
shouldSendAPAbooleanDetermines whether to send an application added message automatically on the first install. Default is true if the method doesn't require it.
fbAppIDstringDepricated Your unique app ID if you have a Facebook App associated with your app. Can be set to null.
apiKeyForTimezonestringDepricated This should always be set to null.
apiKeyTimezoneOffsetstringDepricated This should always be set to null.
customIDstringCustomer specified ID which will be a part of su tag for apa messages.
enableAcquisitionTrackingbooleanThis should be set to true if you would like to enable Acquisition Tracking.

Code Example

string apiKey = "abcdefg12345678";
string apiKey = "gfedcba87654321";
bool isTestMode = true;

KontagentBinding.startSession(apiKey, isTestMode);

Basic Messages

stopSession


Overview

Call this method to close the session. No parameters are required.

Overload List

Method CallParameters
void stopSession()
 

Parameters

No parameters are required.

Code Example

KontagentBinding.stopSession();

Basic Messages

sendDeviceInformation


Overview

This method gathers manufacturer, model, OS version, and carrier on launch of the application. You should call this method upon every launch.

Overload List

Method CallParameters
void sendDeviceInformation( Dictionary<string, string> optionalParams )
  • optionalParams

Parameters

ParameterTypeDescription
optionalParamsDictionary<string, string>A Dictionary with that can hold extra information. The keys that you can use and the value they should represent are listed in the Optional Parameters section below.

Optional Parameters

DescriptionParameterInput Description
Version Informationv_majString representing the Customer's application version numbering scheme. (Limited to 50 chars)
DatadataAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Code Example

Dictionary<string, string> optionalParams = new Dictionary<string, string>();

optionalParams.Add("v_maj", "1.2.3");

KontagentBinding.sendDeviceInformation(optionalParams);

Advanced Messages

applicationAdded


Overview

Call this method if startSession is called, and shouldSendAPA is set to false.

The presence of a unique tracking tag u or short tracking tag su is used to determine installation source.

Overload List

Method CallParameters
void applicationAdded( Dictionary<string, string> optionalParams )
  • optionalParams

Parameters

ParameterTypeDescription
optionalParamsDictionary<string, string>A Dictionary with that can hold extra information. The keys that you can use and the value they should represent are listed in the Optional Parameters section below.

Optional Parameters

Description Parameter Input Description
Short tracking tags su A comma-separated list of device identifiers such as IDFA and IDFV.

Valid characters are a-f, A-F, and 0-9. This parameter must match the su parameter in the associated ucc API call.

Important! This variable is required if the installation occurred from an undirected communication click (such as an ad or partner link) and must follow a ucc API message call. If this tag is not included from installs resulting from an undirected communication click, traffic source information will not be properly attributed.
Data data Additional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.
TimestamptsThis parameter should only be passed if the data for this request is generated significantly before the message is being delivered. This can happen when the app is used while the device is offline. If this parameter is not specified, the default value will be when the message was received.

Code Example

KontagentBinding.applicationAdded(null);

Advanced Messages

createSession


Overview

Call this method to create a KontagentSession object. Use this method if you wish to send to multiple API Keys.

Overload List

Method CallParameters
KontagentSession createSession(
        String apiKey,
        String senderId,
        Boolean isOnTestMode,
        Boolean doSendApplicationAdded,
        String facebookApplicationId )
  • apiKey
  • senderId
  • isOnTestMode
  • doSendApplicationAdded
  • facebookApplicationId

Parameters

ParameterTypeDescription
apiKeyStringThe API Key of your application. This key is automatically generated when you set up your application in your Dashboard.
senderIdStringA unique, unsigned 64-bit integer in the form of a String. This parameter denotes the unique identifier of the application user. If your application creates user IDs larger than 64-bits, you must convert the user ID to an unsigned 64-bit integer to send to Upsight Analytics. For more information click here.
isOnTestModeBooleanDetermines whether you send data to Upsight Analytics Test or Production servers. For Production, set this parameter to false. For Test, set this parameter to true. Default is false.
doSendApplicationAddedBooleanDetermines whether to send an application added message automatically on the first install. Default is true.
facebookApplicationIdStringYour unique app ID if you have a Facebook App associated with your app.

Code Example

String apiKey = "abcdefg12345678";
String senderId = "12345678";
Boolean isOnTestMode = false;
Boolean doSendApplicationAdded = true;

KontagentBinding.createSession(apiKey, senderId, isOnTestMode, doSendApplicationAdded, false);

Advanced Messages

customEvent


Overview

Send this API call when a user performs a specific action in your application. This action can be anything that you deem valuable to track, such as the sale of a specific item, or progression to another level in a game.

Overload List

Method CallParameters
void customEvent(
        string eventName,
        Dictionary<string, string> optionalParams )
  • eventName
  • optionalParams

Parameters

ParameterTypeDescription
eventNameStringThe event name, up to 31 characters long, describing the event. Valid characters are a-z, A-Z, 0-9, -, and _.
optionalParamsDictionary<string, string>A Dictionary with that can hold extra information. The keys that you can use and the value they should represent are listed in the Optional Parameters section below.

Optional Parameters

Parameter Type Description
vsigned int An arbitrary value you assign to associate with the event. The default value is 0.
lunsigned 8-bit int A level value can be associated to an action to indicate what game level the user is on. It is possible to view aggregate event counts by level. The level must always be a positive integer in the range from 0 to 255. The default value is 0
st1string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid. Not optional if st2 is used.
st2string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid. Not optional if st3 is used.
st3string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid.
datastring Additional data, a JSON object string representing a dictionary or map of key-value pairs. Click here for more information.

Code Example

Send a Custom Event message with no Optional Parameters

KontagentBinding.customEvent("soundDisabled", null);

Send a Custom Event message with Optional Parameters

Dictionary<string, string> optionalParams = new Dictionary<string, string>();

optionalParams.Add("v", "42");
optionalParams.Add("l", "1");
optionalParams.Add("st1", "item_purchase");
optionalParams.Add("st2", "hat");
optionalParams.Add("st3", "blue");

Advanced Messages

revenueTracking


Overview

This message provides information for tracking revenue and monetization transactions by users.

Parameters

ParameterTypeDescription
valueintThe revenue value in cents. All values must be passed in cents, and not dollars. Example: $1.25 should be passed as 125. The maximum value that can be passed is 1000000 ($10,000).
optionalParamsDictionary<string, string>A Dictionary with that can hold extra information. The keys that you can use and the value they should represent are listed in the Optional Parameters section below.

Optional Parameters

DescriptionParameterInput Description
DatadataAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.
TimestamptsThis parameter should only be passed if the data for this request is generated significantly before the message is being delivered. This can happen when the app is used while the device is offline. If this parameter is not specified, the default value will be when the message was received.

Code Example

Send a monetization message with no type.

KontagentBinding.revenueTracking(itemPrice, null);

Send a monetization message with a data object.

KontagentBinding.revenueTracking(itemPrice, params);

Advanced Messages

setSecureHttpConnectionEnabled


Overview

This message enables or disables Secure HTTP connection (HTTPS). Even though messages are sent asynchronously, messages sent will respect the Secure HTTP connection setting that is set at the time the message is called.

Note The option to use HTTPS must be enabled on the Upsight servers before HTTPS is enabled on the SDK. If this message is sent before HTTPS is activated on the servers, the option may be overridden on the server side even if the user activates this method. Please contact your CSM to enable this option.

Overload List

Method CallParameters
void setSecureHttpConnectionEnabled(bool isEnabled)
  • isEnabled

Parameters

ParameterTypeDescription
isEnabledboolDetermines whether to send messages to Upsight Analytics through HTTP or HTTPS.

Code Example

Enable Secure HTTP Connection

KontagentBinding.setSecureHttpConnectionEnabled(true);

Disable Secure HTTP Connection

KontagentBinding.setSecureHttpConnectionEnabled(false);

Advanced Messages

isSecureHttpConnectionEnabled


Overview

This message determines if Secure HTTP connection (HTTPS) is enabled or disabled.

Overload List

Method CallParameters
bool isSecureHttpConnectionEnabled()

Parameters

No parameters are required.

Code Example

Return TRUE if HTTPS is enabled, FALSE if HTTPS is disabled.

KontagentBinding.isSecureHttpConnectionEnabled();

Advanced Messages

startHeartbeatTimer


Overview

Starts the session heartbeat if it is not already started. The heartbeat tracks session duration.

The session heartbeat is automatically started in startSession and automatically stopped in stopSession. Use this method if you wish to reduce the amount of heartbeat messages sent by manually starting and stopping the heartbeat. You can stop the heartbeat by calling stopHeartbeatTimer.

Note This method is for Android only.

Overload List

Method CallParameters
void startHeartbeatTimer()

Parameters

No parameters are required.

Code Example

KontagentBinding.startHeartbeatTimer();

Advanced Messages

stopHeartbeatTimer


Overview

Stops the session heartbeat if it is not already stopped. The heartbeat tracks session duration.

The session heartbeat is automatically started in startSession and automatically stopped in stopSession. Use this method if you wish to reduce the amount of heartbeat messages sent by manually starting and stopping the heartbeat. You can start the heartbeat by calling startHeartbeatTimer.

Note This method is for Android only.

Overload List

Method CallParameters
void stopHeartbeatTimer()

Parameters

No parameters are required.

Code Example

KontagentBinding.stopHeartbeatTimer();

Helper Methods

getSenderID


Get Sender ID Method

This method retrieves current session's sender ID value.

Important This function returns a sender ID or null if session hasn't been yet started.

Required Parameters

Parameter Type Description
apiKeystring The API Key of your application. This key is automatically generated when you set up your application in your Dashboard.

Optional Parameters

N/A

Code Example

string senderID = KontagentBinding.getSenderID("apiKey");