Upsight logo Back to top

Getting Started

Basic Integration


To begin, you will need to download the Unity SDK.

Integrating Upsight's Unity SDK is done through a few simple steps:

  1. Open up your Unity project and double-click the Upsight unitypackage to import it into your project

  2. Switch to either the iOS or Android platform from the build settings menu.

  3. In the Upsight Dashboard under Settings > Applications > App Name locate your App Token and Public Key.

  4. In Unity, under Tools > Upsight, open the Configuration Wizard and add in your App Token and Public Key for your desired platform.

    Configuration Wizard

  5. Create a new script attached to your main scene, calling Upsight.init()

  6. You can now build your application and view your entire basic integration! You can confirm that everything runs as expected in the debugging section.

Debugging


To see whether or not Upsight is successfully integrated after you added in your App Token and Public Key, you can turn on full debug logging or look at our Real Time dashboard.

To turn on debugging call the Upsight.init() method, pass UpsightLoggerLevel.Debug into the Upsight.setLoggerLevel() method.

Upsight.setLoggerLevel(UpsightLoggerLevel.Debug);

If you run the app now, you’ll see debug output showing SDK activity in XCode's debug console or Logcat.

After just integrating only Upsight.init(), you should see:

  • Running the app will generate an upsight.config.expired message, this tells the Upsight server to send over a new SDK configuration.

  • The server will send a response to this message. The response body defines the configuration for the SDK. You will see the response JSON in the debug console.

Sessions are being tracked, and session-based metrics will be available:

  • Starting the app will generate an upsight.session.start message.

  • Stowing the app will generate an upsight.session.pause message.

  • When the app returns to the foreground an upsight.session.resume message is generated if you have been in the background for less than the configured session gap time. Otherwise, a new upsight.session.start is sent, and the session ID is updated.

    Note The session gap time is configured on the server.

  • With the exception of the upsight.session.start and upsight.config.expired messages, these messages are batched and sent together: they will not show up on the dashboard immediately. You'll see a message like this in the debug window when the batch of events are sent:

    batch queue sending batch to endpoint: http://batch.upsight-api.com/batch/v1/
    

Since the dashboard takes time to process the messages, to track these messages in real time and ensure proper integration go to Real Time:

  • On the Upsight Dashboard, on the left side navigation bar, click the Real Time link.

  • From the drop down menu at the top of the Real Time dashboard, select your app.

  • Click the Filter button.

Integration Center

Custom Events


Custom events are easier than ever to implement now. Once you have initialized the library, you can track an event just by setting the event name and properties as indicated in the code example below:

var properties = new Dictionary<string, object> ();
properties.Add ("Age", "42");
properties.Add ("Gender", "Male");

Upsight.recordCustomEvent ("event_name", properties);

Set properties to null or simply call Upsight.recordCustomEvent ("event_name") if there are no properties you want tracked. Otherwise create a Dictionary representing the event properties you wish to track. Examples include user's age, gender, or plan type. Additionally, periods can be used in the custom event name to create event hierarchy such as category.subcategory.my_event_name.

On Android, if there are events that you wish to record that should not be associated to any session you can call Upsight.recordSessionlessCustomEvent instead.

Note The debug console will now show the event has been stored. However until a sufficient number of events has been accumulated, or the batch of messages has reached a certain age, the messages will not actually be transmitted to the server. This will help improve the end user's network performance and battery life.

Milestones and Billboards - Getting and Showing Content


Milestones

Milestones are a new way to track user movement through your app and allow you to manage exactly when and where a user sees content. Milestones are triggered when your user reaches a point in your application that you want to track or take action on. After a user hits a Milestone of a given scope, the user will be able to see content from an open Billboard that also has that same scope.

To set a milestone, simply call the following function and assign a scope:

Upsight.recordMilestoneEvent ("main_menu");

Milestones have one required property - a "Scope" that uniquely describes that location in your application. Examples of Scope are "main_menu", "inventory", or "level_up". Additionally Milestone can track event properties by using a Dictionary:

var properties = new Dictionary<string, object> ();
properties.Add ("Age", "42");
properties.Add ("Gender", "Male");

Upsight.recordMilestoneEvent ("event_name", properties);

After Milestones are implemented within the app, they need to be registered in the dashboard. To navigate there go to Settings > Applications > App Name > App Settings > Milestones > Add Milestone.

Milestones

“Milestone scope” is what you called the milestone in your app. “Description” is just used to help you differentiate them.

Important "Scope" is a user defined String that must be all lowercase with no spaces.

Billboards

In order to display marketing content, a 'Billboard' must exist and be open. A billboard is like an empty frame into which the SDK can place content it receives from the server. Like milestone events, each billboard is associated with a Scope. The content returned after a Milestone event will have the same Scope as the Milestone.

There are two basic steps to showing content:

  1. Record a Milestone event for the scope. This delivers content to your device to be shown when a billboard is open.
  2. Call Upsight.prepareBillboard ("scope"); to prepare a billboard for the given scope. This allows any content delivered for that scope to be shown.

Note The Upsight Unity SDK plugin only allows one billboard to be shown at a time. When you create an additional billboard, all previous billboards will be removed.

After Billboards are implemented within the app, a Campaign will need to be created in the dashboard before content will be shown.

Important By changing when your code starts performing steps 1 and 2 above, you can control when your content will be shown. Steps 1 and 2 do not need to be performed in a particular order, and content won't be shown until both steps have been performed. This allows you to control content freely. Additionally, you can use the isContentReadyForBillboardWithScope method to check that content is ready for display before even opening up a billboard. isContentReadyForBillboardWithScope will only return true after a milestone of the same scope has been called.