Upsight logo Back to top

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.

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