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.
To begin, you will need to download the Unity SDK.
Integrating Upsight's Unity SDK is done through a few simple steps:
Open up your Unity project and double-click the Upsight unitypackage
to import it into your project
Switch to either the iOS or Android platform from the build settings menu.
In the Upsight Dashboard under Settings > Applications > App Name locate your App Token and Public Key.
In Unity, under Tools > Upsight, open the Configuration Wizard and add in your App Token and Public Key for your desired platform.
Create a new script attached to your main scene, calling Upsight.init()
You can now build your application and view your entire basic integration! You can confirm that everything runs as expected in the debugging section.
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.
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 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.
“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.
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:
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.
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
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.
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.
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.
Since SDK version 4.9, Upsight provides methods to set default privacy settings and consent status for all users. These allow you to indicate whether or not potential Personally Identifiable Information (PII) should be captured for users, in case they have yet to consent to collection.
setEnhancedPrivacyApplicability
allows you to set a specific level of enhanced privacy for the user. There are three possible settings, indicated by the UpsightEnhancedPrivacyApplicability
enum:
Auto
; With this, Upsight's servers will determine whether or not a user applies for enhanced privacy (eg they are in a country that must comply to GDPR). With this on, certain Upsight features, such as mediation, may not be available for users in areas where enhanced privacy applies.Yes
; Enhanced privacy applies to the user.No
; Enhanced privacy does not apply to the user.getEnhancedPrivacyApplicability
will return the current status of a user's privacy applicability as a value of UpsightEnhancedPrivacyApplicability
.
setEnhancedPrivacyConsentGranted
allows you to indicate to Upsight whether or not a user has consented for additional data collection. This should be changed at any time a user either consents or revokes consent. Your application is responsible for requesting and properly passing in the current consent status to the Upsight SDK. By default this is set to false
.
isEnhancedPrivacyConsentGranted
returns the current status of whether or not a user has given consent.
If this returns false
, that represents that the user has not consented or revoked consent to the collection of Personally Identifiable Information. If this returns true
, that represents that the user has consented to the collection of Personally Identifiable Information.
EnhancedPrivacyApplicibiltyLevel | Within EU? | Consent Granted? | Upsight Data Collection |
---|---|---|---|
AUTO | YES | YES | Normal |
AUTO | YES | NO | Limited |
AUTO | NO | YES | Normal |
AUTO | NO | NO | Normal |
YES | YES | YES | Normal |
YES | YES | NO | Limited |
YES | NO | YES | Normal |
YES | NO | NO | Limited |
NO | YES | YES | Normal |
NO | YES | NO | Normal |
NO | NO | YES | Normal |
NO | NO | NO | Normal |
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.
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).
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.
Upsight provides Unity events you can subscribe to after a session is started or resumed.
There are two Upsight Session events:
sessionDidStartEvent
is called when a new session is created. You can call the full set of Upsight SDK APIs, except creating an UpsightContext
.
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.
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:
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.
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.
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 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.
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.
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 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.
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 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.
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) {
}
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.
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:
RecordImpressionEvent()
- Send this once the content of the campaign is rendered and displayed to the user.RecordClickEvent()
- Send this if the user interacts with your campaign such as accepting a dialog prompt.RecordDismissEvent()
- Send this once the campaign is no longer on screen. 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.
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:
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:
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.
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 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.
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.
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>
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.
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.
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.
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.
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
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);
The easiest way to get device identifiers is by using Real Time in your dashboard once your app is integrated with the Upsight SDK.
Click on an event and search for ids.idfa
. An IDFA will look something like 236A005B-700F-4889-B9CE-999EAB2B605D
.
Click on an event and search for ids.idfv
. An IDFV will look something like C305F2DB-56FC-404F-B6C1-BC52E0B680D8
.
Click on an event and search for ids.android_id
. An Android ID will look something like bedb0ff7a69ddf5b
.
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.
opt_out = FALSE
.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.
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.
Returns an int
representing the current latest session number.
Upsight.getLatestSessionNumber()
Returns a long
representing the timestamp
of the start of the latest session.
Upsight. getLatestSessionStartTimestamp()
Returns true
if there is content ready for a given scope
.
Upsight.isContentReadyForBillboardWithScope( string scope )
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.
Upsight.getSid()
To begin, you must declare your managed variables in the Upsight Project Configuration Wizard under Tools->Upsight->Project Configuration Wizard:
As seen above, managed variables contain a variety of fields:
string
, boolean
, integer
, and float
. In the example image this is set to Bool
for the first entry.enable_extended_mode
for the first entry.string
, int
, float
, true
, or false
depending on the type chosen. In the example image this is set to false
for the first entry.Enable enhanced UI
for the first entry.For integers and floats there are two additional fields:
0
for both the coins
and strength
entries.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.
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)
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.
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
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.
On iOS, make a copy of Assets/Editor/Upsight/settings.plist
On Android, make a copy of Assets/Plugins/Android/upsight-manifests/AndroidManifest.xml
On iOS, make a copy of Assets/Editor/Upsight/UpsightSDK/UpsightUXMVariables.plist
On Android, make a copy of Assets/Editor/Upsight/uxm_values.json
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
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
.
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.
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
.
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.