Upsight logo Back to top

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:

$ ./

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.

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

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

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

    Note -ObjC tag is case sensitive.


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:"

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.

Integration Center

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.

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.