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 tvOS SDK provides our full analytics suite of features for your AppleTV applications.
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.
The Upsight tvOS SDK uses appledoc to generate visually appealing API method documentation in the form of HTML. These docs are fully indexed and browsable through Xcode.
In order to use the appledoc, extract the tvOS SDK zip file and run the following commands:
$ ./install_docsets.sh
Note Installing the Upsight documentation will fail if you have not installed any documentation yet. If the installation process fails, navigate to the Downloads section of Xcode settings and download any other documentation modules. Then run the script again.
To see the Upsight Documentation, click Help > Documentation and API Reference. On the left hand side, you will find the UpsightKit Documentation.
To begin, you will need to download the tvOS SDK.
Integrating Upsight's tvOS SDK is as simple as 3 easy steps.
From the Upsight SDK folder, drag UpsightKit.framework
into your Project’s Framework folder in the Xcode Navigator window. Ensure that UpsightKit.framework
was added to the Build Phases section of the target settings. Then add CoreTelephony.framework
and AdSupport.framework
provided by Apple to the Build Phases section.
Navigate to the 'Info' page of the project settings. Under 'tvOS Target Properties' create a key called UpsightAppToken
with String
as a Type and copy your Upsight App Token to the value field. Next create a key called UpsightPublicKey
with String
as a Type and copy your App Public Key as a string to the value field. These are provided on the Upsight dashboard under Settings > Applications > App Name.
In the Build Settings section of the target, add -ObjC to the Other Linker Flags field.
Note -ObjC tag is case sensitive.
To start with, turn on full debug logging:
#import <UpsightKit/UpsightKit.h>
at the top of your AppDelegate.m
file.application:didFinishLaunchingWithOptions:
add [Upsight setDefaultLogLevel:UpsightLoggerLevelDebug];
This will let you see the SDK's debug output while you confirm the integration. Once you have finished the integration, you can remove this line.If you run the app now, you’ll see debug output showing SDK activity in XCode's debug console.
After finishing basic integration:
Sessions are being tracked, and session-based metrics will be available:
Since the dashboard takes time to process the messages, to track these messages in real time and ensure proper integration go to Real Time. Go to Real Time > Select App > Click on Filter.
To check Console logs for iOS devices use Xcode. It can be downloaded online directly from Apple's App Store. Hook your device up to your computer via USB cable, run Xcode and navigate to Windows > Devices > "Your device". Click the triangle in the bottom left hand corner of the device window in Xcode to show console logs.
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.
To add a custom event:
#import <UpsightKit/UpsightKit.h>
[Upsight recordAnalyticsEventWithName:@"event_name" properties:@{ @"Age": @"42", @"Gender": @"Male"}];
Set properties to nil
if there are no properties you want tracked. Otherwise create an NSDictionary representing the event properties you wish to track. Examples include user's age, gender, or plan type. Additionally, for custom events periods can be used in the event name to create event hierarchy such as category.subcategory.my_event_name
.
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.
To receive optional callbacks when an Upsight Session starts or resumes you must do the following:
#import <UpsightKit/UpsightKit.h
at the top of your AppDelegate.h file.@interface AppDelegate : UIResponder <UIApplicationDelegate, UpsightSessionDelegate>
application:didFinishLoadingWithOptions:
method:
[USSessionInfo setUpsightSessionDelegate:self];
UpsightKit/USSessionInfo.h
There are four Upsight session callbacks:
upsightSessionWillStart
- triggered when a new session, as defined by the Upsight SDK is about to start. Useful for setting user attributes before any events are sent to Upsight. It is not safe to trigger events. Passes an USSessionInfo
object with information about the previous session.upsightSessionDidStart
- triggered when a new session has finished starting. Useful for sending events immediately when a new session starts.upsightSessionWillResume
- triggered when a session is going to resume. Useful for setting user attributes before any events are sent to Upsight. Also passes an USSessionInfo
object with information about the current session. It is not safe to send events during this time.upsightSessionDidResume
- triggered when a session has finished resuming. Useful for sending events immediately 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 Info section of your project's settings.
UpsightUserAttributes
.UpsightUserAttributes
.Note If you would like to send null
for a date
attribute as a default you will have specify the following date 9999-12-31T23:59:59Z
.
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 attributes called 'myNumberAttribute', 'myStringAttribute', myDateAttribute, and myBoolAttribute with types Number, String, Date, and Bool respectively, you would retrieve their values with the following:
NSNumber *aNumber = [USUserAttributes numberForKey:@"myNumberAttribute"];
NSString *aString = [USUserAttributes stringForKey:@"myStringAttribute"];
NSDate *aDate = [USUserAttributes dateForKey:@"myDateAttribute"];
BOOL aBool = [USUserAttributes boolForKey:@"myBoolAttribute"]
This returns the default values as defined in the Info settings, unless you change the values, like this:
[USUserAttributes setNumber:@(10) forKey:@"myNumberAttribute"];
[USUserAttributes setString:@"aString" forKey:@"myStringAttribute"];
[USUserAttributes setDate:[NSDate date] forKey:@"myDateAttribute"];
[USUserAttributes setBool:YES forKey:@"myBoolAttribute"]
Now, NSNumber *aNumber = [USUserAttributes numberForKey:@"myNumberAttribute"];
will return 10, NSString *aString = [USUserAttributes stringForKey:@"myStringAttribute"];
will return aString, [USUserAttributes dateForKey:@"myDateAttribute"]
will return the date and time when the setDate:forKey: method was called and [USUserAttributes boolForKey:@"myBoolAttribute"]
will return YES
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.
Note You cannot programmatically add or remove User Attributes. They must be added and removed through the Info settings. 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.
Upsight makes it easy to track and analyze revenue you earn from customers with monetization events. There are two separate methods that you can use to track monetization. If you wish to track a purchase made through the App Store, use the following method from the Upsight class:
+ (void)recordInAppPurchaseEventWithResolution:(USPurchaseResolution)resolution
product:(NSString *)product
quantity:(NSUInteger)quantity
price:(float)price
currency:(NSString *)currency
transactionIdentifier:(NSString *)transactionIdentifier;
resolution - one of:
USPurchaseResolutionBuy
if the purchase was successful.USPurchaseResolutionCancel
if the user canceled the purchase.product - The product name, as provided by the productIdentifier
property of an SKProduct
object.
quantity - The number of products purchased during the transaction, as set in the quantity property of an SKPayment
object.
price - the value returned by price.floatValue
where price is the price property of an SKProduct
object.
currency - the value returned by [priceLocale objectForKey:NSLocaleCurrencyCode]
where priceLocale
is the priceLocale
of an SKProduct
object.
transactionIdentifier - A value extracted from the SKTransaction
object sent by Apple during the StoreKit exchange.
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 store, you can use this method instead:
+ (void)recordMonetizationEventWithTotalPrice:(float)totalPrice currency:
(NSString *)currency;
totalPrice - the total amount of the transaction.
currency - typically retrieved using [[NSLocale currentLocale] objectForKey:NSLocaleCurrencyCode]
.
This feature allows you to use Managed Variables in your application; these are variables whose values are set by the server. Managed Variables are referenced by tag.
To begin, you must declare your Managed Variables in a file called UpsightUXMVariables.plist
The default field should contain the value the Managed Variable should return if it has not been updated by the server.
The description field should contain a string
that describes what the Managed Variable is used for.
The type field should define the type of the Managed Variable. Variables can be of type string
, integer
, float
, or boolean
.
The tag field defines the name by which you will reference the variable in your code. Each tag must be unique within your app.
The max field is only used by number type variables. It defines the largest number value that the Managed Variable can return; any larger values will be replaced by this value.
The min field is only used by number type variables. It defines the smallest number value that the Managed Variable can return any smaller values will be replaced by this value.
In the source file where you want to access a managed variable, import the Upsight framework.
#import <UpsightKit/UpsightKit.h>
Then, call the USManagedVariable class method listed below that corresponds to the type of the managed variable you are accessing.
+ (id<USManagedString>)managedStringWithTag:(NSString *)aTag;
+ (id<USManagedInteger>)managedIntegerWithTag:(NSString *)aTag;
+ (id<USManagedFloat>)managedFloatWithTag:(NSString *)aTag;
+ (id<USManagedBoolean>)managedBooleanWithTag:(NSString *)aTag;
The returned object will have a value
method appropriate to its type. The value
method returns the most recent value retrieved from the server, or the default value if no value has been retrieved yet.
id<USManagedString> uxmString = [USManagedVariable managedStringWithTag:@"personage_name"];
NSLog(@"The current value of personage_name is %@", uxmString.stringValue);
If you wish to be notified when the system has updated the values of the Managed Variables, you can set a delegate on the variable observer:
[Upsight variableObserver].delegate = self;
The object you assign as the variableObserver's delegate must conform to the USManagedVariableObserverDelegate
protocol. This call must be made no earlier than the call to your app delegate's applicationDidBecomeActive:
method.
If you implement the optional observer:didSynchronizeManagedVariables:
method, the Managed Variable observer will call your implementation immediately after all the managed variables have been updated. Included in this call is an NSArray
containing the tags of all the variables that were updated.
If you keep any references to Managed Variables that you access before the call to observer:didSynchronizeManagedVariables:
you need to refresh those references afterward in order to see the new values.
If you wish to prevent updates to the Managed Variables you can override observerShouldSynchronizeManagedVariables:
. If you return NO
from your implementation of this method none of the managed variables will be updated. This method is called every time a session starts, so you will have the chance to accept updates you previously rejected.
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 senderID];
A method that gets information about the current Upsight session by returning an USSessionInfo
object. If no session is active, this method will return the most recent session information. If no session has been recorded, then a default USSessionInfo
object with sessionNumber of nil
, and sessionStartTime
of 0
will be returned.
[USSessionInfo getLatestSessionInfo];
Keeping your production data clean in Upsight is important to maintaining the data integrity of your most important metrics. To do this, it just takes a few steps to implement.
First create Test and Production Applications in the Upsight Dashboard.
Note each Application’s Token and Public Key.
In XCode Go to Project Settings > Build Settings and click to add a User Defined Setting.
Set name as UPSIGHT_TOKEN
and repeat to create UPSIGHT_PUBLIC_KEY
.
Expand each setting and enter values for Debug and Release configurations from Upsight Dashboard corresponding to Testing and Production applications copied from step 2.
Go to the Info section of Build Settings. Update UpsightAppToken
to your $(UPSIGHT_TOKEN)
and update UpsightAppPublicKey
to your $(UPSIGHT_PUBLIC_KEY)
.
The easiest way to get a device's IDFA is by using Real Time in your dashboard once your app is integrated with the Upsight SDK.
Simply click on an event and search for ids.idfa
. For example, the IDFA will look something like 236A005B-700F-4889-B9CE-999EAB2B605D
.
ids.idfa
in the console log.By searching for the ids.idfa
parameter in the console log, you can find the IDFA. For example, the IDFA will look something like 236A005B-700F-4889-B9CE-999EAB2B605D
.
Note If the "Limit Ad Tracking" setting in Settings-> Privacy->Advertising is on, Upsight will ignore the IDFA sent, which effectively means the device will be unrecognizable to Upsight (i.e. it will be treated as a new device, it will not act as a test device even if it is registered as a test device with the proper IDFA, no user activity will be tracked, etc.)
You can also reset your IDFA from this screen. If you do a full hardware reset on your device, your IDFA will be reset to something else.
The easiest way to get a device's IDFV is by using Real Time in your dashboard once your app is integrated with the Upsight SDK.
Simple click on an event and search for ids.idfv
. For example, the IDFV will look something like C305F2DB-56FC-404F-B6C1-BC52E0B680D8
.
The easiest way to get a device's IDFV is by checking your console log while opening your app that is integrated with the Upsight SDK.
ids.idfv
in the console log.By searching for the ids.idfv
parameter in the console log, you can find the IDFV. For example, the IDFV will look something like C305F2DB-56FC-404F-B6C1-BC52E0B680D8
.