Upsight logo Back to top

Quick Start Guide

The Basics


Before You Start

Although the Upsight Enterprise iOS SDK is built on top of our Data Collection API, we encourage you to use the SDK rather than the Data Collection API directly. Using the SDK ensures consistency in how metrics are calculated (e.g. the SDK sends a pgr message every 30 seconds to calculate session duration) and ensures all data gets sent to the Upsight Analytics servers, even with the intermittent activity (e.g. offline play) that occurs with mobile use.

The Upsight Enterprise iOS SDK currently supports iOS 6+ and armv7 iOS devices. Older devices, (such as iPad 1, iPhone 3g, and the original iPhone, for example) are not supported.

Download SDK

Instrumenting Your Application


Step 1

Create QA and Production Apps on the Upsight Analytics Dashboard. We recommend creating two versions of your application to safely verify your instrumentation without sending malformed information to your Production application.

  1. From the Upsight Analytics Dashboard add an application instance. Give it a name similar to: My_App_Name - QA. This will be the application your instrumented application will send test data to.

  2. From the Upsight Analytics Dashboard add another application instance. Give it a name similar to: My_App_Name - Production. This will be the application that will house all your live data.

screenshot - ios add application

Note Each of these application instances has a unique API Key. These keys are automatically generated for you when the application is created. Make note of these API Keys as they are used when instrumenting the applications. The API Key is used to determine which application instance in Upsight Analytics your data is sent to. During the QA phase, you will want to direct your data to your QA application instance. This is done by specifying the QA application's API Key in your method calls. Once you go live, change your calls to use your Production application's API Key to send data to your production application instance.

Step 2

Download the Upsight Analytics Enterprise iOS SDK. For the newest version of the SDK navigate to the Downloads Page.

The zip archive will contain two directories:

  • Kontagent.framework
  • Kontagent.library

For basic instrumentation, you will make use of the Kontagent.framework folder. The Kontagent.library folder contains the files used for Acquisition Tracking. For more information on Acquisition Tracking visit our iOS Mobile Acquisition Guide.

Step 3

If you are upgrading from a previous version, remove the existing Upsight files and folders from your XCode project.

Step 4

Move the Kontagent.framework directory into your XCode project's file folder under the Frameworks directory.

Step 5

Under your project targets, select Build Phases.

Under Link Binary With Libraries, add the following frameworks:

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • CoreData.framework
  • libz.dylib or libz.tbd

Step 6

Under your project targets, select Build Settings.

Under Other Linker Flags (OTHER_LDFLAGS), add the following linker flags:

  • -ObjC

Step 7

If you are building on XCode 7, you must turn off App Transport Security or add specific exemptions to your Info.plist. The analytics SDK mostly uses HTTPS but has the potential to make a few unencrypted calls. These calls can occur when an application is started up for the first time while offline or on first run in rare network situations.

To disable ATS entirely, add a dictionary item in your Info.plist called NSAppTransportSecurity with a boolean item NSAllowsArbitraryLoads set to YES.

The specific domains that the analytics SDK accesses are code.jquery.com, api.geo.kontagent.net, test-server.kontagent.com and mobile-api.geo.kontagent.net. To add domain-specific exemptions add a dictionary key NSExceptionDomains and keys for each above URL followed by two member keys set to YES for NSIncludesSubdomains and NSExceptionAllowsInsecureHTTPLoads or paste in the following code directly into your NSAppTransportSecurity item in xcode and name it NSExceptionDomains:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>test-server.kontagent.com</key>
    <dict>
        <key>NSIncludesSubdomains</key>
        <true/>
        <key>NSExceptionAllowsInsecureHTTPLoads</key>
        <true/>
    </dict>
    <key>api.geo.kontagent.net</key>
    <dict>
        <key>NSExceptionAllowsInsecureHTTPLoads</key>
        <true/>
        <key>NSIncludesSubdomains</key>
        <true/>
    </dict>
    <key>code.jquery.com</key>
    <dict>
        <key>NSIncludesSubdomains</key>
        <true/>
        <key>NSExceptionAllowsInsecureHTTPLoads</key>
        <true/>
    </dict>
    <key>mobile-api.geo.kontagent.net</key>
    <dict>
        <key>NSExceptionAllowsInsecureHTTPLoads</key>
        <true/>
        <key>NSIncludesSubdomains</key>
        <true/>
    </dict>
</dict>
</plist>

Your Info.plist should have an item that looks like the below:

info.plist

For more information on setting exemptions please see Apple's ATS Technote.

Step 8

In your Application Delegate, import the Kontagent header file.

#import "Kontagent/Kontagent.h"

Step 9

In your Application Delegate, invoke the startSession method in the applicationDidBecomeActive method. This will start an Upsight Analytics session.

Important If you are using the Enterprise and regular SDKs, make sure to call the startSession method before making an PHPublisherOpenRequest Open Call.

After the startSession message, you should immediately call the sendDeviceInformation method. This method automatically gathers the device type (e.g. iPad 2, iPhone 4s etc.), carrier information, and OS version (e.g. iOS 7) when invoked. If you would like to track the application version for the user, pass the parameter v_maj. More details.

[Kontagent startSession:@"<MY_APP_QA_API_KEY>" mode:kKontagentSDKMode_TEST];
[Kontagent sendDeviceInformation:nil];

Note In the above code, replace the string <MY_APP_QA_API_KEY> with the API Key that was generated when you created your QA application instance.

In your Application Delegate, modify the applicationWillResignActive method to include a stopSession message. This will end an Upsight Analytics session.

[Kontagent stopSession];

Step 10

Test that your messages are well formed using the Upsight Analytics Test Servers. Do this by setting your instrumentation to test mode, running the instrumented application, and viewing the data on the Test Servers.

Note In the startSession message above, we already set the mode to send data to the Upsight Analytics Test Servers. This is done by using the kKontagentSDKMode_TEST flag.

View your data on the Upsight Analytics Test Server:

  1. Navigate to the Upsight Analytics Dashboard.
  2. In the top right corner, place your mouse over the Tools option.
  3. In the menu that appears, click the Test Server option.
  4. Select your QA Application.

When you run your newly instrumented application in kKontagentSDKMODE_TEST mode, it will send messages to the Test Server to verify your message structure. It is not recommended to move on from this step unless you have an OK status on every message.

The messages you should expect to see are a single Application Added message, a User Information message, and a Page Request message every 30 seconds while the application is running. The Page Request messages are the Upsight Analytics Heartbeat. These messages inform the servers that your application is active.

screenshot - ios test server

Note By enabling debug logging prior to making any calls, the Upsight Analytics API will maximize the amount of debug logging that will be generated.

To enable debugging, invoke the enableDebug message.

[Kontagent enableDebug];

To disable debugging, invoke the disableDebug message.

[Kontagent disableDebug];

Step 11

Contact your CSM for a full QA of your application.

Step 12

When you have verified your instrumentation, you will be ready to switch from your QA Application to your Production Application. To do so, modify the startSession message in your code to contain the Production Application's API Key instead of the QA Application's API Key. The code will look similar to:

[Kontagent startSession:@"<MY_APP_PRODUCTION_API_KEY>" mode:kKontagentSDKMode_PRODUCTION];

Visit the iOS Method Reference Guide for more detailed information on the iOS SDK methods.

iOS Mobile Acquisition Tracking

iOS Application with MAT Enabled without IDFA


  1. Instrument Upsight's iOS SDK to your application per the iOS Instrumentation Guide.
  2. Drag and drop the libKontagent_MOBACQ.a file to your project in xCode.
  3. Replace the Kontagent object call with the following:

    NSMutableDictionary* aConfiguration = [[NSMutableDictionary alloc] init];
    
    // api key
    [aConfiguration setObject:@"<YOUR_API_KEY_HERE>" forKey:KT_SESSION_API_KEY_CONFIG_KEY];
    
    // production/test mode
    [aConfiguration setObject:[NSNumber numberWithInteger:kKontagentSDKMode_TEST] forKey:KT_SESSION_MODE_CONFIG_KEY];
    
    // enable acquisition tracking
    [aConfiguration setObject:[NSNumber numberWithBool:true] forKey:KT_SESSION_ENABLE_ACQUISITION_TRACKING];
    
    // start the Kontagent session
    [Kontagent startSession:aConfiguration];
    
  4. Verify that you have enabled MAT with the MAT Test Server.

iOS Mobile Acquisition Tracking

iOS Application with MAT Enabled with IDFA


  1. Instrument Upsight's iOS SDK to your application per the iOS Instrumentation Guide.
  2. Drag and drop libKontagent_MOBACQ_IDFA.a into your project in xCode.
  3. Add the AdSupport.framework to your build phases.
  4. Replace the Kontagent object call with the following:

    NSMutableDictionary* aConfiguration = [[NSMutableDictionary alloc] init];
    
    // api key
    [aConfiguration setObject:@"<YOUR_API_KEY_HERE>" forKey:KT_SESSION_API_KEY_CONFIG_KEY];
    
    // production/test mode
    [aConfiguration setObject:[NSNumber numberWithInteger:kKontagentSDKMode_TEST] forKey:KT_SESSION_MODE_CONFIG_KEY];
    
    // enable acquisition tracking
    [aConfiguration setObject:[NSNumber numberWithBool:true] forKey:KT_SESSION_ENABLE_ACQUISITION_TRACKING];
    
    // start the Kontagent session
    [Kontagent startSession:aConfiguration];
    
  5. Verify that you have enabled MAT with the MAT Test Server.

iOS Mobile Acquisition Tracking

iOS Unity Application with MAT Enabled without IDFA


  1. Import the custom Upsight package.
  2. UnchecklibKontagent_MOBACQ_IDFA.a in the Items to Import dialogue window.
  3. UnchecklibKontagent_FB.a in the Items to Import dialogue window.
  4. Click Import button.
  5. Follow instructions for using Unity without IDFA on the Unity website.
  6. Replace the Kontagent object call with the following:

    public static void startSession(
    string apiKey,
    bool enableTestMode,
    string senderId,
    bool shouldSendAPA,
    string apiKeyForTimezone,
    string apiKeyTimezoneOffset,
    string customID,
    string fbAppID,
    bool enableAcquisitionTracking
    );
    
  7. Verify that you have enabled MAT with the MAT Test Server.

iOS Mobile Acquisition Tracking

iOS Unity Application with MAT Enabled with IDFA


  1. Import the custom Upsight package.
  2. UnchecklibKontagent_MOBACQ.a in the Items to Import dialogue window.
  3. UnchecklibKontagent_FB.a in the Items to Import dialogue window.
  4. Click Import button.
  5. Include the AdSupport.framework.
  6. Replace the Kontagent object call with the following:

    public static void startSession(
    string apiKey,
    bool enableTestMode,
    string senderId,
    bool shouldSendAPA,
    string apiKeyForTimezone,
    string apiKeyTimezoneOffset,
    string customID,
    string fbAppID,
    bool enableAcquisitionTracking
    );
    
  7. Verify that you have enabled MAT with the MAT Test Server.

iOS Mobile Acquisition Tracking

MAT Test Server Validation


To verify that you have enabled MAT, compile your test build in your selected IDE and run the project. You should see an APA install message fire on start session. The su tag of the APA will have 9 device ID hash permutations (as seen in the image below). If your device happens to have an IMEI value, we will also capture this. In that case there will be 16 values in the su array.

This is to ensure that when we receive an incoming device ID from an external source, we are able to match and attribute at least one value in the su array from click-to-install.

screenshot - mat ios test server

FAQ


How do I instrument my app for acquisition tracking?

To instrument your iOS app for acquisition, follow the iOS Acquisition Setup on this page.

How much does the Upsight SDK add to my app size?

The Upsight SDK typically adds around 1 MB to the final application size.

How many messages are buffered when the device is offline?

By default, the number of messages queued is limited to 499. When the queue is full, new API messages will be dropped instead of being added to the queue.

To change the size of the queue, call the following function in the applicationDidBecomeActive method:

[Kontagent changeMaxQueueSize:<NEW_SIZE> forSessionApiKey:@"<MY_API_KEY>"];

Note Each API Message will use about 100 bytes of space.

How long does it take for out of order data received by Upsight to calculate metrics?

Our offline tracking is seven (7) days. The numbers are populated initially on the day the data is received, and then recalculated and placed where appropriate. Therefore, during that seven (7) day time period, your numbers will fluctuate.

How do I find PATH_TO_KONTAGENT or the path to Kontagent.framework?

You have moved Kontagent.framework onto your project in XCode. Now, in the project navigator in XCode (to open project navigator, click on the file folder icon on the left panel). Right click on Kontagent.framework and select Kontagent.framework in Finder.

How do I send a CustomID?

Please refer to the following example:

[Kontagent startSession:@"<MY_APP_API_KEY>" senderId:nil mode:kKontagentSDKMode_PRODUCTION shouldSendApplicationAddedAutomatically:YES customID:@"<MY_CUSTOM_ID>"];

How do I obtain my API Key?

Login to the Upsight Analytics Dashboard. Click on the edit link beside your application name to open the Edit Application window. Your API Key is listed there.

How do I set up for tracking custom ad campaigns?

You need to be able to match up device IDs from your ad provider with Upsight. On the SDK side, as long as your ad provider provides you with the algorithm they will use on ad clicks, you can pass this in when calling startSession under the customID field.