Upsight logo Back to top

Unity

Overview

Upsight Unity SDK

Upsight is the most comprehensive analytics and marketing platform for web and mobile apps. We are building a business engine to help our customers better understand user behavior, decide what it means, and act to impact key goals.

Upsight's Unity SDK Requires iOS 8+, Android API Level 16+ (Jellybean), and Unity 5.0 or later (Unity 2017+ recommended)

If you have any questions, contact Upsight Support. We also recommend reviewing our Optimization Guides to learn the best practices and get the most out of your Upsight integration.

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.

Getting Started

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

Getting Started

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.

Getting Started

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.

Push

Prerequisites

For iOS Push prerequisites, please take a look at the iOS Push Prerequisites Section of the iOS Integration Guide

For Android Push prerequisites, please take a look at the Android Push Prerequisites Section of the Android Integration Guide

Push

Integrate Push

Integrate Push

To integrate push notifications in your app, you must register for push notifications at app launch in order to correctly handle pending notifications received after your app has been killed. For Android, you must also set the FCM Application ID and FCM API Key in the Project Configuration Wizard.

If at any point you would like to unregister or reregister a device for push notifications simply call Upsight.unregisterForPushNotifications() and Upsight.registerForPushNotifications() respectively.

Note for iOS When Unity creates an Xcode build of your project, please make sure to check Preprocessor.h and that #define UNITY_USES_REMOTE_NOTIFICATIONS 1 is present in the file. If this is equal to #define UNITY_USES_REMOTE_NOTIFICATIONS 0, Unity believes push is not active in your application and has disabled Push. To enable push, please change this flag to the value of 1.

Push

Image Push

Upsight's Unity SDK version 4.3.2 and higher supports rich image push on both iOS and Android. On SDK versions 4.4 and later, image push is automatically set up when an application is built with Unity versions 5.4 and above.

Developers using Unity 4 or an older version of the Upsight SDK will have to manually import their project into Xcode 8 and follow the manual iOS steps to add support for image push.

Additionally, developers using Unity 5 versions prior to 5.4 will need to manually configure their development team in Xcode. This is a new requirement in Xcode 8, and older versions of Unity will not set this when making a build.

Manual Unity Instructions

Push

Customizing Android Notifications

On Android, you can choose a custom push icon for your application. To do so, go to Upsight -> Project Configuration Wizard and scroll down to the Android notification icon section. Here, you can upload a 72x72 .png or .jpg that will be used as your push notification icon.

Android Push Icon

GDPR

Location

Upsight allows you to manually set both a user's home location and current location rather than relying on IP address. This is especially applicable for countries covered by the GDPR. If current or home country are manually set, they override any derived country information that would otherwise attribute a user to a specific country for reporting and targeting purposes.

Current Country

setCurrentCountry allows you to specify any 3-character country code to set as the user's current country. If you would like to clear this value, simply pass null.

getCurrentCountry returns the set current country string of the user or null if none was set.

Current country takes precedence over any derived country information (eg from IP).

Home country

setHomeCountry allows you to specify any 3-character country code to set as the user's home country. If you would like to clear this value, simply pass null.

getHomeCountry returns the set home country string of the user or null if none was set.

Home country takes precedence over current country and any derived country information.

Session Lifecycle Callbacks

Session Callbacks

Upsight provides Unity events you can subscribe to after a session is started or resumed.

There are two Upsight Session events:

  1. sessionDidStartEvent is called when a new session is created. You can call the full set of Upsight SDK APIs, except creating an UpsightContext.

  2. sessionDidResumeEvent is triggered when an existing session is resumed. You can call the full set of Upsight SDK APIs, except creating an UpsightContext.

You can also call getLatestSessionNumber() and getLatestSessionStartTimestamp() at any time to get information about the current session. If there is no running session, the method will return information about the last known session.

Content Callbacks

Content Callbacks

Important Please note the Content Callbacks are only available in Upsight SDK 4.7.1 and above.

Upsight provides Unity events in UpsightManager that you can subscribe to for information regarding the content lifecycle.

There are three Upsight Content events:

  1. onPartnerInitializedEvent(string partnerName) is triggered after each partner module is initialized. You can use this to determine when it is safe to utilize partner functionality such as mediated ads. "fuse" is the partner name used for mediation.

  2. onContentAvailableEvent(string scope, Dictionary<string, string> params) is triggered when content is available and ready to be displayed for the given scope. You can use this event to open a billboard to display content immediately.

  3. onContentNotAvailableEvent(string scope, Dictionary<string, string> params) is triggered if content fails to load. You can use this event to trigger another milestone request to load content again.

User Attributes

User Attributes

User Attributes are properties you define which appear on every event sent to the Upsight servers. To implement User Attributes, you must first define the attributes in the User Attributes sections of Upsight > Edit Settings.

  1. Click "Add Custom Attribute" to add a new custom attribute
  2. Choose the name, type, and default value of each attribute

Note For date attributes, they must be of the format YYYY-MM-DDThh-mm-ss and if you want to by default send null simply enter the value 9999-12-31T23:59:59.

You can retrieve and set values for the User Attributes you have created within your code. You can access them by name. Assuming you used the preceding steps to create two attributes called myIntegerAttribute and myStringAttribute with type Integer and String respectively, you would retrieve their values with the following:

int aNumber = Upsight.getUserAttributeInt ("myIntegerAttribute");
string aString = Upsight.getUserAttributeString ("myStringAttribute");
DateTime aDate = Upsight.getUserAttributeDate ("myDateAttribute");
float aFloat = Upsight.getUserAttributeFloat ("myFloatAttribute");
bool aBool = Upsight.getUserAttributeBool ("myBoolAttribute");

This returns the default values as defined in the Info settings, unless you change the values, like this:

Upsight.setUserAttributeInt ("myIntegerAttribute", 10);
Upsight.setUserAttributeString ("myStringAttribute", "newString");
Upsight.setUserAttributeString("myStringListAttribute", "aStringListItem1,aStringListItem2");
Upsight.setUserAttributeDate ("myDateAttribute",   DateTime(2014, 03, 23, 6, 54, 00, DateTimeKind.Utc));
Upsight.setUserAttributeFloat ("myFloatAttribute", 10.5f);
Upsight.setUserAttributeBool ("myBoolAttribute", true);

Now, the get calls will return 10 and "newString", and a DateTime object representing 2014-03-23T06:54:00.

Once you have set User Attributes in your code, add it as a Custom Attribute in your dashboard under Settings > Applications > App name > Edit app > Custom Attributes. This will allow you to segment and create analytics using your User Attributes.

Custom Attributes

When creating Custom Attributes in the dashboard, select the type which matches the type defined in your Manifest. For String attributes, you may select string or a list of strings. string attributes allow you do store and match on a single item, for example, Team, City or Gender. A list of strings allows you to store a list of items and then create segments based on whether or not that list contains, or does not contain, specific items. This could be used to store a list of purchases, subscriptions, or other items, and is a more effective way to match against set which may contain lots of different items than creating individual boolean attributes, one for each item in the list. A list of strings should still be defined with the string type in your Manifest and should be composed by comma separating the items into a single string when you set the value.

Note You cannot programmatically add or remove User Attributes. They must be added and removed through the Project Configuration Wizard. Adding and removing User Attributes will cause a discontinuity in the data stored on Upsight's servers, so it is something you should do only with forethought and planning.

Virtual Goods Promotion (VGP) and Rewards

Granting Rewards and VGP Purchases

Virtual Goods Promotions (VGP) and Rewards are two types of content that can be set up through the dashboard and displayed in a billboard. These are different from other content units in that you, as a programmer, need to know whether or not the customer has accepted the offer.

In the event your user receives a reward or agrees to purchase a virtual good a callback is fired. You can listen for these callbacks by registering your own method to be invoked when they occur:

UpsightManager.billboardDidReceiveRewardEvent += myRewardMethod;

UpsightManager.billboardDidReceivePurchaseEvent += myPurchaseMethod;

These methods pass in a UpsightReward or UpsightPurchase object:

void myRewardMethod(UpsightReward reward) {
  // track granting the reward using the UpsightReward object
}

void myPurchaseMethod(UpsightPurchase purchase) {
   // track IAP using the UpsightPurchase object
}

By providing an implementation for one or both of these callbacks, your code is given the opportunity to take appropriate action based on what your user has done.

In the case of a VGP, it is likely you will need to broker a transaction between your user and Apple's App Store or Google Play. Once that transaction is finished you can track the results using an InAppPurchase event.

Important Please note that the Reward Product Identifier provided by Upsight to your application will be in lower case and can only contain alphanumeric characters and underscores.

Validating Rewards

Upsight offers you the ability to callback directly to your server when a reward is granted for validation or to send over reward data from your device. You can read about configuring server to server reward callbacks here as well as validating Upsight sent messages here.

If you would like to validate the reward that the Upsight server has granted to the device, you can do so by sending reward signature data to your server and performing an operation on the contents. You can get the signature data for a reward by calling reward.getSignatureData().

This JSON object contains the product, sid, quantity, nonce, and signature of the reward. You use the product, sid, quantity, and nonce along with your app's secret_key to produce the signature provided in the payload on your server.

Below is an example of python reward verification:

import base64
import hashlib
import hmac


def validate_signature_data(signature_data, secret):
    """Validates the signature for Upsight rewards.

    >>> secret = 'YOUR_32_CHAR_SECRET_KEY'
    >>> signature_data = {
    ...     'idfv': 'AAAAAAAA-0000-0000-0000-000000000000',
    ...     'nonce': '0437121572:rambo_cat:1',
    ...     'product': 'rambo_cat',
    ...     'quantity': 1,
    ...     'sid': '10000000000000000000',
    ...     'sig4': 'joQiupsyEe10Ui83TCPuScVBfOo',
    ...     'token': 'YOUR_APP_TOKEN'
    ... }
    >>> validate_signature_data(signature_data, secret)

    If the signature is invalid, or there is a problem with the signature_data
    dictionary, ValueError will be raised:

    >>> signature_data['sig4'] = 'invalid'
    >>> validate_signature_data(signature_data, secret)
    Traceback (most recent call last):
      ...
    ValueError: incorrect signature

    :param dict signature_data: A dictionary of signature data, from the SDK.
    :param str secret: Your app secret string.
    :raises ValueError: if the signature is invalid.
    """
    for required in ('nonce', 'sig4', 'token'):
        if required not in signature_data:
            raise ValueError('signature_data is missing {}'.format(required))

    identifiers = {}
    for identifier in ('device', 'gid', 'ifa', 'mac', 'odid', 'odin',
                       'idfv', 'sid'):
        value = signature_data.get(identifier)
        if not value:
            continue
        if isinstance(value, unicode):
            value = value.encode('utf8')
        identifiers[identifier] = value
    if not identifiers:
        raise ValueError('signature_data is missing identifiers')

    message = ':'.join((':'.join(str(identifiers[key])
                                 for key in sorted(identifiers.keys())),
                        signature_data['token'],
                        signature_data['nonce']))
    signature_hash = hmac.new(str(secret), message, hashlib.sha1)
    signature = base64.urlsafe_b64encode(signature_hash.digest()).rstrip('=')
    if not hmac.compare_digest(signature_data['sig4'], signature):
        raise ValueError('incorrect signature')

Native Messaging

Overview

Native Messaging lets you leverage Upsight’s Segmentation and Targeting to deliver campaigns where you can implement your own native display, instead of using one of Upsight’s interstitial campaigns.

Note Native Messaging is supported on Upsight SDK versions 4.4.0 and above.

Native Messaging campaigns are delivered through Milestones and Billboards as with our other campaigns types, plus your own handling of the returned data. See the Milestones and Billboards section for the core concepts, and the below instructions for the additional steps required to start using Native Messaging.

Native Messaging campaigns are designed to create native experiences by collecting the inputs required to build a desired experience then sending that data to the correct devices at the correct times. Before a Native Messaging campaign is published, the application source code will need to be updated to handle and/or display the expected payload inputs. Once a campaign has been triggered and a payload has been passed back, it is up to the developer to have the infrastructure in place to handle and display their intended experience. This responsibility includes using Upsight provided helper methods and objects to track events such as clicks and impressions, as well as controlling the destruction of campaign content.

The Upsight SDK provides several methods to access the data contained in a payload and will return native objects when possible. These accessor methods are made available through UpsightData objects. UpsightData objects are an Upsight created object type with numerous Native Messaging specific capabilities. When a Native Messaging campaign is triggered, a UpsightData object will be returned through a delegate method, where the developer can then access the contents of the UpsightData object and build their experience.

Important Images are handled differently than the other supported data types. Images sent in a Native Messaging campaign are pre-fetched and stored on disk in order to reduce latency when rendering an image once a milestone is triggered. Pre-fetched images are accessed via a file path and can be handled in your source code using a UpsightData.Image object along with the provided helper methods.

Native Messaging

Integrate For Native Messaging

Receiving Data From a Native Messaging Campaign

To receive data from a Native Messaging Campaign, register a listener to the billboardDidReceiveDataEvent. Your listener will get invoked when a campaign with a native message payload is received and a billboard of the same scope is open. While the billboard itself will not render any content, it is still used to make the payload available.

UpsightManager.billboardDidRecieveDataEvent += myDataMethod

This method passes in an UpsightData object that you can use as indicated below.

void myDataMethod(UpsightData data) {

}

Accessing Content in a Native Messaging Campaign Object

UpsightData objects provide instance methods to access the different types of objects contained in the native message.

Accessor method signatures for payloads generated using the Basic input format:

public string GetString(string key);
public bool GetBool(string key);
public int GetInt(string key);
public float GetFloat(string key);
public Image GetImage(string key);
public Color GetColor(string key);

UpsightData.Image is an object that contains properties for the image's loaded-on-disk file path, width, and height. Please use this information to load the image into memory and display it as you see fit.

Native Messages created using the ‘Raw’ input method will can be accessed via the GetRawData() method. This method provides a string containing raw data in the same structure and format as entered in the campaign on the Upsight Dashboard.

public string GetRawData();

Important After the billboard containing the native message is dismissed, all data associated with the returned UpsightData object will be removed. For images, this means that the image on disk that is being referenced will be deleted. Please make a separate local copy of any images that you would like to persist past the life of the billboard.

Tracking User Interaction

Once the Native Messaging campaign is ready to be displayed to the user, the interaction the user has with the campaign can be tracked by calling various methods on your UpsightData object. The available methods are:

  1. RecordImpressionEvent() - Send this once the content of the campaign is rendered and displayed to the user.
  2. RecordClickEvent() - Send this if the user interacts with your campaign such as accepting a dialog prompt.
  3. RecordDismissEvent() - Send this once the campaign is no longer on screen.
  4. Destroy() - Send this once the payload is no longer needed, e.g. after the dismiss button has been pressed or after a user has performed the desired action. This method must be called to inform the SDK that the content interaction is finished.

Important If a campaign is not intended to be seen by users, simply call Destroy() on the payload once it has been processed by the application.

Native Messaging

Example

Here is a sample implementation of a Native Messaging campaign used to render a native interstitial within an application.

In order to have this example display the campaign on a device, a Native Messaging campaign was created on the dashboard by with the following inputs:

example screenshot 1

As well, to handle the expected payload from the Native Messaging campaign, the below implementation was added to the application intended to render the campaign:

private void billboardDidReceiveDataEvent(UpsightData data)
{
    _upsightData = data;
    BackgroundPanel.color = data.GetColor("BGColor");
    ButtonText.text = data.GetString("BodyCopy");
    Texture2D offerTexture = new Texture2D(1, 1);
    offerTexture.LoadImage(File.ReadAllBytes(data.GetImage("OfferImage").ImagePath));
    OfferImage.sprite = Sprite.Create(offerTexture, new Rect(0, 0, offerTexture.width, offerTexture.height), Vector2.zero);
    Texture2D ornamentTexture = new Texture2D(1, 1);
    ornamentTexture.LoadImage(File.ReadAllBytes(data.GetImage("OrnamentImage").ImagePath));
    OrnamentImage.sprite = Sprite.Create(ornamentTexture, new Rect(0, 0, ornamentTexture.width, ornamentTexture.height), Vector2.zero);
    _showingNativeMessage = true;
    BackgroundPanel.gameObject.SetActive(true);
}
public void nativeMessageDismissed()
{
    BackgroundPanel.gameObject.SetActive(false);
    _showingNativeMessage = false;
    _upsightData.RecordClickEvent();
    _upsightData.RecordDismissEvent();
    _upsightData.Destroy();
    _upsightData = null;
}

When a user reaches the appropriate milestone your Native Messaging payload will be delivered to the device. If handled correctly by the source code, the campaign creative will render an experience like this:

example screenshot 2

Native Messaging

Testing a Native Messaging Campaign

Once a native messaging campaign is configured in the dashboard and the application is set up to handle native messaging payloads simply trigger a milestone with the scope of the campaign and open a billboard. Depending on the implementation, the campaign should render and, when clicked, a content displayed, dismissed, and click should display in Upsight RealTime.

Upsight Ad Mediation

Prerequisites

Setting Up Upsight Ad Mediation

In order to set up the Upsight Ad Mediation SDK, you will need to have Upsight Ad Mediation added to your account. Contact your customer success manager for more information.

Upsight SDK Integration

Upsight Ad Mediation can only be used in conjunction with the base Upsight SDK and will show rewarded and non-rewarded video ads through billboards and milestones. Make sure you have completed the basic integration of the Upsight SDK including billboards and milestones before you begin integrating Upsight's Ad Mediation SDK.

Upsight Ad Mediation

Integration

Downloading the SDK

To integrate mediation, you'll need to download be on an Upsight Unity SDK version between 4.1 and 4.9.8. For later versions of the SDK, you can show third party video through announcements. Contact your Customer Success Manager for more information.

Importing

Once downloaded, Mediation is enabled by default. You can disable mediation through a checkbox under Tools -> Upsight -> Project Configuration Wizard.

Important On Android, please ensure that the Write Access is set to external (sdcard) within Unity's Player Settings as Upsight Ad Mediation requires this permission to serve ads on older versions of Android and to serve ads quickly on newer versions. This permission will automatically be added if you use the Upsight-provided build tools.

Please note that on iOS we will automatically append the following permissions to your Info.plist if they are not already present as they are required for some Ad Networks:

<key>NSCalendarsUsageDescription</key>
<string>Advertisement would like to create a calendar event.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Advertisement would like to store a photo.</string>
<key>NSCameraUsageDescription</key>
<string>Advertisement would like to use your camera.</string>
<key>NSMotionUsageDescription </key>
<string>Advertisement would like to use motion for interactive ad controls</string>

Building

On iOS, you will not have to perform any different steps, everything should build as it did before.

On Android your application may hit the method count (dex) limit. In this case, please follow our proguard steps.

Upsight Ad Mediation

Showing Mediated Video Ads

Non Rewarded Video Ads & Static Interstitials

Once you have added the SDK, you will be able to show a mediated video ad or static interstitial at any billboard. Simply go to your Upsight Dashboard and create an Ad Campaign targeting a specific milestone. See the Creating Mediated Ad Campaigns section for more information.

Rewarded Video Ads

Simply implement handling rewards and you will be able to grant your users rewards when running a Rewarded Video Ad campaign at any billboard for a given milestone scope.

Make sure to add the rewards to the dashboard. See Adding Rewards for more information.

Billboard Lifecycle Events

The Upsight Unity SDK offers two events which allow you to hook into when a billboard shows content or is dismissed.

When a user sees content in a billboard a onBillboardAppearEvent is fired and when a user dismisses a billboard a onBillboardDismissEvent is fired. You can listen for these events by registering your own method to be invoked when they occur:

UpsightManager.onBillboardAppearEvent += myAppearMethod;

UpsightManager.onBillboardDismissEvent += myDismissMethod;

These methods pass in a string indicating the scope of the billboard and on onBillboardAppearEvent an UpsightContentAttributes object:

void myAppearMethod(string scope, UpsightContentAttributes attributes) {
  // perform some action when the user sees a billboard or a billboard with this specific scope
}

void myDismissMethod(string scope) {
  // perform some action when the user dismisses a billboard or a billboard with this specific scope
}

The UpsightContentAttributes object contains a Type enum with information about what type of content the billboard contains:

public class UpsightContentAttributes
{
    public Type ContentType { get; private set; }
    public string ContentProperties { get; private set; }
    public enum Type
    {
        UNKNOWN,
        ANNOUNCEMENT,
        INTERNAL_CROSS_PROMOTION,
        REWARDS,
        VIRTUAL_GOODS_PROMOTION,
        OPT_IN,
        ADS,
        MORE_GAMES,
        VIDEO_CAMPAIGN,
        CUSTOM_VIEW,
        MEDIATION,
    }
}

By providing an implementation for one or both of these events, your code is given the opportunity to take appropriate action based on what your user has done.

Monetization

Upsight makes it easy to track and analyze revenue you earn from customers with monetization events. There are three separate methods that you can use to track monetization.

If you wish to track a purchase made through the Google Play Store, use the following methods:

  Upsight.recordGooglePlayPurchase(quantity, currency, price, totalPrice, product, responseCode, inAppPurchaseData, inAppDataSignature, properties)

  • quantity - The number of products purchased during the transaction, as set in the quantity property of an SKPayment object or Google Equivalent.

  • currency - The currency as a 3-character ISO 4217 code.

  • price - The price of the product.

  • totalPrice - the total price of the transaction.

  • product - The product name.

  • responseCode - The value mapped to the RESPONSE_CODE in the purchase response data from onActivityResult. See Google Play In-app Billing Version 3 API.

  • inAppPurchaseData - The value mapped to the INAPP_PURCHASE_DATA in the purchase response data from onActivityResult. See Google Play In-app Billing Version 3 API.

  • inAppDataSignature - The value mapped to the INAPP_DATA_SIGNATURE in the purchase response data from onActivityResult. See Google Play In-app Billing Version 3 API.

  • properties - (optional) a dictionary of custom properties to send to the server for use in DataMine.

If you wish to track a purchase made through the iOS App Store, use the following methods:

  Upsight.recordAppleStorePurchase(quantity, currency, price, transactionIdentifier, product, UpsightPurchaseResolution, properties)

  • quantity - The number of products purchased during the transaction, as set in the quantity property of an SKPayment object.

  • currency - the NSLocaleCurrencyCode from the priceLocale of an SKProduct object

  • price - The value returned by price.floatValue where price is the price property of an SKProduct object.

  • transactionIdentifier - A value extracted from the SKTransaction object sent by Apple during the StoreKit exchange.

  • product - The product name, as provided by the productIdentifier property of an SKProduct.

  • UpsightPurchaseResolution - one of:

    • UpsightPurchaseResolution.Buy if the purchase was successful.
    • UpsightPurchaseResolution.Cancel if the user canceled the purchase.

  • properties - (optional) a dictionary of custom properties to send to the server for use in DataMine.

When the SDK sends an InAppPurchase event recorded with this method, it attaches the receipt object from the transaction with the App Store. The Upsight server then validates this receipt with the Apple servers.

If you have a purchase to record that did not involve the Apple or Google Play store, you can use this method instead:

Upsight.recordMonetizationEvent(totalPrice, currency, UpsightPurchaseResolution, product, price, quantity, properties)

  • totalPrice - the total amount of the transaction.

  • currency - the currency used to make the purchase

  • UpsightPurchaseResolution - one of:

    • UpsightPurchaseResolution.Buy if the purchase was successful.
    • UpsightPurchaseResolution.Cancel if the user canceled the purchase.

  • product - (optional) the identifier of the product purchased

  • price - (optional) the per-unit price of the purchase

  • quantity - (optional) the number of units purchased

  • properties - (optional) a dictionary of custom properties to send to the for use in DataMine

Location Tracking

Enabling location tracking will allow you target and segment your users based on their geographical location. That data will be attached to all the events sent from the device. Once you have location information simply pass it to Upsight using:

Upsight.setLocation(lat, long);

Finding Device Identifiers

The easiest way to get device identifiers is by using Real Time in your dashboard once your app is integrated with the Upsight SDK.

IDFA

Click on an event and search for ids.idfa. An IDFA will look something like 236A005B-700F-4889-B9CE-999EAB2B605D.

IDFV

Click on an event and search for ids.idfv. An IDFV will look something like C305F2DB-56FC-404F-B6C1-BC52E0B680D8.

Android ID

Click on an event and search for ids.android_id. An Android ID will look something like bedb0ff7a69ddf5b.

COPPA

If you operate a mobile app directed to children under 13 that collects, uses, or discloses personal information from children or you otherwise have actual knowledge that you are collecting, using, or disclosing personal information from children under 13, the Children’s Online Privacy Protection Act (COPPA) may apply to you. If so, you may have responsibilities relating to how you collect, disclose, or use personal information from such children.

To assist you in your data collection, disclosure and use compliance obligations, we have added to the platform a “opt-out“ setting to the Unity SDK, so you can indicate whether you want Upsight to limit data collection and use, and serve only contextually targeted ads.

Child-directed settings and features

  • A default value for the opt-out flag in the SDK that can be changed by the publisher. The default value out-of-the-box will be opt_out = FALSE.
  • Functionality in the SDK to change the opt-out flag for the individual user. Publisher may use this setting if it utilizes age-gating functionality, for example.

Example

If you have an app that is directed at 8-10 year olds, you can set the default value for the opt-out flag to be TRUE for all users. Then, you can add an age-gating mechanism to the app, and change the opt-out flag to FALSE for users that you learn to be 13 or older.

Targeting Opt-Out

To comply with COPPA regulations and standards, Upsight has provided a mechanism for your app to opt-out of collecting user information. The user opt-out status inside your app is indicated by

Upsight.getOptOutStatus()

The default opt-out status is set to FALSE. If you need to opt-out of collecting user information, simply call Upsight.setOptOutStatus and set the value to TRUE.

Note Although Upsight has enabled this function, you are still responsible for providing an appropriate user interface for user opt-out.

For official information about COPPA, the recent amendments, and a list of FAQs provided by the FTC, please consult the FTC website.

Helper Methods

getLatestSessionNumber

Description

Returns an int representing the current latest session number.

Example 

Upsight.getLatestSessionNumber()

Helper Methods

getLatestSessionStartTimestamp

Description

Returns a long representing the timestamp of the start of the latest session.

Example 

Upsight. getLatestSessionStartTimestamp()

Helper Methods

isContentReadyForBillboardWithScope

Description

Returns true if there is content ready for a given scope.

Example 

Upsight.isContentReadyForBillboardWithScope( string scope )

Helper Methods

getSid

Description

Invoke this method to get your Sid. Sid is an internal user identifier Upsight uses. In situations, you may want to use this identifier for your own internal purposes or store it on your servers.

Example 

Upsight.getSid()

Managed Variables

Integration

To begin, you must declare your managed variables in the Upsight Project Configuration Wizard under Tools->Upsight->Project Configuration Wizard:

Managed Unity Screenshot

As seen above, managed variables contain a variety of fields:

  • type - The type of the variable as it will be indicated on the Upsight Dashboard. Valid values are the strings string, boolean, integer, and float. In the example image this is set to Bool for the first entry.
  • tag - the string by which you will reference the variable in your code. In the example image, this is set to enable_extended_mode for the first entry.
  • default - the default value of a variable. Can be any string, int, float, true, or false depending on the type chosen. In the example image this is set to false for the first entry.
  • description - A description of what the variable is to be used for. In the example image, this is Enable enhanced UI for the first entry.

For integers and floats there are two additional fields:

  • min - The minimum value this variable can have. In the example image, this is set to 0 for both the coins and strength entries.
  • max - The maximum value this variable can have. In the example image, this is set to 10000 for the coins entry and 1 for strength entry.

Once your variables are declared, you can then access them from your code by calling one of the below methods based on the type of variable you have stored:

  • Upsight.getManagedBool( string tag )
  • Upsight.getManagedString( string tag )
  • Upsight.getManagedInt( string tag )
  • Upsight.getManagedFloat( string tag )

These methods will return a bool, string, int, or float with the value currently stored which represents the most recent value returned from the server or the default value if no values have been returned.

If you do not wish to apply updates to managed variables during the run of your application you can pass false to Upsight.setShouldSynchronizeManagedVariables( bool value ).

Additionally, you can choose to be notified when variables change by registering with the UpsightManager.managedVariablesDidSynchronizeEvent callback. This callback will contain a list of tags that have been updated.

Attribution Tracking

Setting Attribution Source

Upsight SDK version 4.2.0 and above will automatically pull in attribution sources from the Google Play Store.

For iOS or if you would like to manually set your attribution source, you can do so through through the use of the recordAttributionEvent method:

Upsight.recordAttributionEvent(campaign, creative, source, pub_data)

Proguarding

Exporting from Unity

To export your Unity build for use in Android Studio, simply go to build settings, select Gradle under "Build System", check the "Export Project" button and click "Export".

To enable proguard, open the build.gradle in your exported project and replace the buildTypes {...} block with the following: 

    packagingOptions {
        exclude 'META-INF/services/javax.annotation.processing.Processor'
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/license.txt'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'LICENSE.txt'
        exclude 'license.txt'
        exclude 'LICENSE'
        exclude 'license'
        exclude 'META-INF/NOTICE.txt'
        exclude 'META-INF/notice.txt'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'NOTICE.txt'
        exclude 'notice.txt'
        exclude 'NOTICE'
        exclude 'notice'
        exclude 'META-INF/rxjava.properties'
    }
    buildTypes {
       release {
           minifyEnabled true
           proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.txt'
       }
       debug {
           minifyEnabled true
           proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.txt'
       }
    }

Replace the proguard-rules.txt in your exported project with the one here.

After the project is exported, you can either open the project in Android Studio or build your application directly with gradle with a gradle wrapper:

Note Unity exported projects don't come with a gradle wrapper by default, you will either have to download one separately or open your project in Android Studio to be prompted to download one.

Running with Gradle

If you do not have Gradle already installed on your system, you can either download and install Gradle and generate a wrapper file by following the Gradle Wrapper User Guide. Please note that Unity uses version 2.10 of Gradle.

Alternatively, you can download an Upsight-provided gradlew wrapper from here and unzip into your exported project.

Once you have a wrapper, you can build your application using the gradlew scripts:

On Windows:

.\gradlew.bat assembleDebug #for debug builds
.\gradlew.bat assemble #for release

On OSX:

./gradlew assembleDebug #for debug builds
./gradlew assemble #for release

Troubleshooting / FAQ

Upgrading from the Unity 4-style package (4.3.2 and earlier) to the Unity 5 package

If you would like to migrate data (keys, managed variables, user attributes) please follow these steps first. Otherwise, you can proceed to the Updating section.

Backing up your data

Keys, Tokens, and User attributes

On iOS, make a copy of Assets/Editor/Upsight/settings.plist On Android, make a copy of Assets/Plugins/Android/upsight-manifests/AndroidManifest.xml

Managed Variables

On iOS, make a copy of Assets/Editor/Upsight/UpsightSDK/UpsightUXMVariables.plist On Android, make a copy of Assets/Editor/Upsight/uxm_values.json

Updating

This WILL NOT migrate over any keys, uxm values, user attributes. If you want to save any data make sure you you followed the steps outlined in the Backing up your data section first as well as the Restoring Old Data section below.

Delete Editor/Upsight
Delete Plugins/Upsight
Delete all Upsight folders from Plugins/Android, as of 4.3.2 these are:                                                                                                  

analytics-4.3.2                                
core-4.3.2                                     
google-advertising-id-4.3.2                    
google-push-services-4.3.2                     
libs                                           
managed-variables-4.3.2                        
marketing-4.3.2                                
marketplace-4.3.2                              
mediation-4.3.2                                
mediation-ad-network-ac-2.6.7                  
mediation-ad-network-al-2.6.7                  
mediation-ad-network-m2-2.6.7                  
mediation-ad-network-m2-lib-2.6.7              
mediation-ad-network-m2-lib-base-2.6.7         
mediation-ad-network-m2-lib-interstitial-2.6.7 
mediation-ad-network-m2-lib-rewardedvideo-2.6.7
mediation-ad-network-mraid-2.6.7               
mediation-ad-network-ss-2.6.7                  
mediation-ad-network-u2-2.6.7                  
mediation-ad-network-u2-lib-2.6.7              
mediation-ad-network-vast-2.6.7                
mediation-common-2.6.7                         
mediation-core-2.6.7                           
mediation-lib-2.6.7                            
play-services-base-8.4.0                       
play-services-basement-8.4.0                   
play-services-gcm-8.4.0                        
play-services-measurement-8.4.0                
rxandroid-1.1.0                                
support-v4-23.4.0                              
unity-binding-4.3.2                            
unity-binding-base-4.3.2                       
unity-binding-marketing-4.3.2                  
unity-binding-mediation-4.3.2                  
unity-binding-push-4.3.2                       
upsight-manifests                              
volley-1.0.0

Import the your new Upsight (4.3.4 or higher) Unity package

Restoring Old Data

Keys, Tokens, and User attributes

On iOS, copy your saved settings.plist to Assets/Upsight/NativeLibs/iOS/settings.plist On Android, create a upsight-data folder in Assets/Plugins/Android Copy your saved AndroidManifest.xml to Assets/Plugins/Android/upsight-data/AndroidManifest.

Managed Variables

On iOS, Copy your saved UpsightUXMVariables.plist to Assets/Upsight/NativeLibs/iOS/UpsightUXMVariables.plist

On Android, create the folder path Assets/Plugins/Android/upsight-data/res/raw Copy your saved uxm_values.json to Assets/Plugins/Android/upsight-data/res/raw/uxm_schema.json NOTE: The file should be renamed to uxm_schema.json

Run the Project Configuration Wizard and verify that all settings and values are correct.

Troubleshooting / FAQ

Why can't I set types of Custom Attributes on Android?

On Android, Custom Attributes are inferred by the value put into the Configuration Wizard. A number value with a decimal, such as 1.00, would be consider a float. A number value without a decimal, such as 123, would be considered an integer. The true and false values would be considered bool, and anything else would be considered a string.

Troubleshooting / FAQ

Data showing up on Android

On Android, if you have not run the configuration wizard or if you have changed the bundle id of the application you may see the following error in your logs:

com.upsight.android.UpsightException: java.lang.IllegalArgumentException: Unknown URL content://MY_BUNDLE_ID.debug.upsight/model/upsight.datastore.record

If you are getting this error, you will also note that no data is being sent to Upsight's real time page.

As indicated above, this is caused by the bundle_id of your application not being set within the Upsight settings files. The best way to resolve this is to rerun the configuration wizard so that your bundle_id is correctly saved within Upsight's settings.