tvOS

Overview

Upsight tvOS 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 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.

Getting Started

Xcode Documentation

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.

Getting Started

Basic Integration

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

Integrating Upsight's tvOS SDK is as simple as 3 easy steps.

1. 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.

2. 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.

3. In the Build Settings section of the target, add -ObjC to the Other Linker Flags field.

   Note -ObjC tag is case sensitive.

Getting Started

Debugging

To start with, turn on full debug logging:

1. Add #import <UpsightKit/UpsightKit.h> at the top of your AppDelegate.m file.
2. In 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:

• Running the app will generate an "upsight.config.expired" message.
• 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 (set by the server). Otherwise, a new "upsight.session.start" is sent, and the session ID is updated.
• 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. Go to Real Time > Select App > Click on Filter.

Getting Started

Checking Console Logs

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.

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.

To add a custom event:

1. In your view controller’s .m file, add #import <UpsightKit/UpsightKit.h>
2. At the point where you want to send the event, add

[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.

Session Lifecycle Callbacks

Session Callbacks

To receive optional callbacks when an Upsight Session starts or resumes you must do the following:

1. Add #import <UpsightKit/UpsightKit.h at the top of your AppDelegate.h file.
2. Set your application delegate to implement the UpsightSessionDelegate protocol: @interface AppDelegate : UIResponder <UIApplicationDelegate, UpsightSessionDelegate>
3. Add the following line to the top of your application:didFinishLoadingWithOptions: method: [USSessionInfo setUpsightSessionDelegate:self];
4. Implement any of the optional callbacks from UpsightKit/USSessionInfo.h

There are four Upsight session callbacks:

1. 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.
2. upsightSessionDidStart - triggered when a new session has finished starting. Useful for sending events immediately when a new session starts.
3. 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.
4. upsightSessionDidResume - triggered when a session has finished resuming. Useful for sending events immediately

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 Info section of your project's settings.

1. Add a new row to your project's Info list and name it UpsightUserAttributes.
2. Set the new row's type to Dictionary.
3. Click on the disclosure triangle to the left of UpsightUserAttributes.
4. Add a new row for each of the User Attributes you want to include, providing a name, type, and default value for each

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.

Monetization

Monetization

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].

Managed Variables

Integration

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.

Helper Methods

senderID

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 senderID];

Helper Methods

getLatestSessionInfo

Description

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.

Example

[USSessionInfo getLatestSessionInfo];

Best Practice for Testing

Best Practice for Testing

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.

1. First create Test and Production Applications in the Upsight Dashboard.

2. Note each Application’s Token and Public Key.

3. In XCode Go to Project Settings > Build Settings and click to add a User Defined Setting.

   

4. Set name as UPSIGHT_TOKEN and repeat to create UPSIGHT_PUBLIC_KEY.

5. Expand each setting and enter values for Debug and Release configurations from Upsight Dashboard corresponding to Testing and Production applications copied from step 2.

   

6. Go to the Info section of Build Settings. Update UpsightAppToken to your $(UPSIGHT_TOKEN) and update UpsightAppPublicKey to your $(UPSIGHT_PUBLIC_KEY).

   

Finding Device Identifiers

How to find your IDFA

Using Real Time

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.

Using Console Log

1. Connect your device to your computer via USB cable.
2. Check the console log on your computer. To learn how to check the console log, see the iOS console logs article.
3. Open the app that you have integrated the Upsight SDK with.
4. Search for 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.

Finding Device Identifiers

How to find your IDFV

Using Real Time

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.

Using Console Log

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.

1. Connect your device to your computer via USB cable.
2. Check the console log on your computer. To learn how to check the console log, see the iOS console logs article.
3. Open the app that you have integrated the Upsight SDK with.
4. Search for 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.

COPPA