Upsight logo Back to top

Getting Started


Upsight can be installed via cocoapods. To do so, simply add pod 'UpsightKit', '~> 4.9' similar to the following in your Podfile:

target 'MyApp' do
  pod 'UpsightKit', '~> 4.9'

Then run a pod install inside your terminal, or from

If you install the Upsight SDK in this way, you can skip down to the debugging section.

You can read more about our cocoapod on the UpsightKit page.

Xcode Documentation

The Upsight iOS 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 iOS 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 iOS SDK.

Integrating Upsight's iOS 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 Foundation.framework, CoreTelephony.framework, AdSupport.framework, libxml2.tbd , and MediaPlayer.framework provided by Apple to the Build Phases section. Additionally, if you are using Push Notifications or mediation, add the UserNotifications.framework as Optional. Integration step 1

  2. Navigate to the 'Info' page of the project settings. Under 'Custom iOS 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 iOS 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.

Milestones and Billboards - Getting and Showing Content

Getting and Showing Content


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 recordMilestoneEventForScope:@"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 NSDictionary:

[Upsight recordMilestoneEventForScope:@"main_menu" properties:@{ @"Age": @"42", @"Gender": @"Male"}];

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 as a response to a milestone call. 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 three basic steps to show content:

  1. Add the USBillboardDelegate protocol to one of your classes and implement presentingViewControllerForBillboard:
  2. Record a Milestone event for the scope.
  3. Get the USBillboard instance for the scope in which you want to show content, and set its delegate property to point at an instance of the class from step 1.

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 2 and 3 above, you can control when your content will be shown. Steps 2 and 3 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 isContentReady method to check that content was delivered for a given milestone and is ready for display before even opening up a billboard.

Milestones and Billboards - Getting and Showing Content

Example 1: Showing a Billboard in a View Controller

Change the ViewController’s interface definition to indicate that it implements USBillboardDelegate. This requires a <USBillboardDelegate> at the end of the View Controler’s @interface directive at the top of the .m file:

@interface ViewController () <USBillboardDelegate>

Add the following method:

-(UIViewController *)presentingViewControllerForBillboard:(id<USBillboard>)aBillboard
    return self;

In the View Controller’s viewDidAppear: method get the USBillboard for your scope:

id <USBillboard> billboard = [Upsight billboardForScope:@“your_scope_name”];  
billboard.delegate = self;

Finally, send the Milestone:

[Upsight recordMilestoneEventForScope:@“your_scope_name”];

From the billboardDidDismiss callback, clear your billboard delegate to avoid more than one content item being shown at once (optional):

billboard.delegate = nil;

Milestones and Billboards - Getting and Showing Content

Example 2: Showing a Billboard in a Custom Class

In this example, content will be shown whenever MyClass's anInterestingMethod is called

@implementation MyClass

- (instancetype)init
    self = [super init];
    if (nil != self) {

        // Get the billboard for the scope
        id<USBillboard> billboard = [Upsight billboardForScope:@"SomethingInteresting"];

        // Set this object as the billboard's delegate
        // so the billboard can call presentingViewControllerForBillboard:
        billboard.delegate = self;
    return self;

- (void)anInterestingMethod
    // Send a Milestone event here because something intersting happened
    [Upsight recordMilestoneEventForScope:@"SomethingInteresting"];

#pragma mark USBillboardDelegate methods

- (UIViewController *)presentingViewControllerForBillboard:(id<USBillboard>)aBillboard
    UIViewController *topController = [UIApplication sharedApplication].keyWindow.rootViewController;

    while (topController.presentedViewController) {
        topController = topController.presentedViewController;

    return topController;