Support Home > SDK Integration > tvOS SDK Integration

tvOS SDK Integration

DOCUMENT SUPERSEDED: The information that is contained within this document has been superseded. Refer to the current SDK integration support document for the latest integration instructions and procedures.

The Kochava SDK allows advertisers to integrate a single SDK to leverage the hundreds of ad network and publisher partners via Kochava. This limits the number 3rd party SDKs required to run a successful UA strategy and greatly reduces complexity during update cycles.  Find documentation for other SDKs, plugins, and Server-to-Server integrations here.

 

Minimum Requirements:

  • Xcode 7.1
  • tvOS 9.0

Integrating the SDK

 

  1. Add the following to the application’s plist file to allow processing of https traffic:
  2.  

    Make the following additions and project settings changes to the project in order to utilize the Kochava Event Tracking Library.

     

  3. From the attached zip, copy the following files into your project’s folder using Finder:
  4.  

  5. Right-clicking on your project in Xcode, select Add Files to (project name)>Add KochavaTvOS.h to your project.
  6. Click on the project name at the top of the Project Navigator in Xcode.
  7. Select Targets on right pane.
  8. Select Build Phases.
  9. Click Link Binary With Libraries.
  10. If not already listed, using the plus sign, add the following frameworks and libraries:
    • AdSupport.framework
    • libKochavaTvOS.a

     

    NOTE: The first several frameworks and libraries will be found in the main list which appears. The frameworks and libraries located at the bottom of the list will need to be added by Clicking Add Other.

     

  11. In your AppDelegate’s header file, add the following:
    • #import “KochavaTvOS.h”

     

    Within the @interface section:

     

    Under the @interface section:

     

  12. In your AppDelegate’s source file, add the following:
  13.  

    Under @implementation:

     

    In didFinishLaunchingWithOptions:


Calling the Constructor

By calling the Kochava Constructor, you have completed the basic integration with Kochava. The Constructor should be located in the logic of your application where things first startup.

 

The initialization dictionary must contain a Kochava App Id. All other information is optional.

 

Example of an initialization dictionary:

 

More details on each of the boolean values above can be found in their individual setter method documentation below.

The identityLink dictionary may contain one or two key/value pairs of strings and may be used to associate information with the device. For example, you could associate an internal userid which you want to connect to a user’s service identifier. There is more detailed information below under IdentityLink, which can be called at any time.

 

You might create your identityLinkDictionary, to be used in initKochavaWithParams, as follows:

 

When this method is called, the Kochava Tracker reports device and app information to Kochava, should those values be different than the last time this information was reported.

 

Data sent by this method:

  • Device type (AppleTV5,3)
  • iOS name and version (eg: tvOS 9.0)
  • Application version (eg: 1.2)
  • Your Kochava app ID
  • The currency in which your application functions (will default to USD)
  • If you would like to enable console logging of Kochava library events (will default to NO)
  • Limiting app level ad tracking* (is NO by default)

 

NOTE: If limited ad tracking at the application level is desired, with respect to Kochava conversions, turn off ad tracking when the Kochava library is initialized or by an individual method for the purpose of changing the limit ad tracking state, which will be off by default (user opts-in to advertising).

 

With each installation, Kochava gathers device information and sends it to the Kochava servers for analysis across each installation. Further, this information is ONLY sent in the following situations:

  • Upon initial installation
  • When the application is upgraded
  • When the operating system version is upgraded on the host device

 

NOTE: By limiting the times that this information is sent, Kochava is optimizing performance of the SDK and only sending information when changes are made.

NOTE: Kochava persists data in NSUserDefaults. All keys used are prefaced with com.kochava.KochavaTracker. You should be careful not to clear these keys or the SDK may perform unpredictably.


Toggling Console Logging

Console logging will be off by default, unless enabled via either the initial command or the enableConsoleLogging method, which takes only a bool as an argument. If you had enabled console logging when you initialized the library, you can also disable it via this method by passing NO to it.


Toggling Limit-Ad-Tracking

Ad tracking will be ON by default, unless disabled via either the initial command or the setLimitAdTracking method, which takes only a bool as an argument.


Calling Event Methods

Sending Kochava post-install events is not a requirement. To track installation information, you must ONLY call the constructor. While this is true, many advertisers want to understand and correlate the relationship between conversion and attribution source information with post-install behaviors. This can only be done by tracking post-install events.

Once the Constructor is called, the Kochava event tracking method can be called from anywhere within the application. Events will be coupled with the information sent by the Constructor to report events, based on user device and application information.

Events are sent immediately to Kochava servers but queued, should the device not have connectivity.

 

NOTE: Event names may not be prepended with an underscore, as that convention is reserved for Kochava system events. (i.e. _INSTALL).

 

No event pre-registration is required. To instrument an event, simply send an event name via the eventTitle parameter. Optionally, you can also send an eventValue.

 

Uses of the the optional eventValue parameter could be any of the following:

  • Gather in-app purchase information that can be used for LTV calculation.
  • A JSON formatted string, in which you want to track several data points.
  • Another piece of information, paired with the eventTitle.

 

If the string passed in eventValue is all numeric (and may include a decimal point), Kochava will automatically sum the amounts passed in eventValue for the same eventTitle. For example, if you sent the purchase amount of in-app purchases in eventValue and named eventTitle “IAP – Purchase Price”, Kochava would add up all the purchase amounts for you and present them as a total for “IAP – Purchase Price”.

Regardless of what is passed in eventValue, Kochava’s user dashboard will let you access all the data passed in eventValue for any eventTitle, and present a count of all times trackEvent passed any given eventTitle.

 

NOTE: If you pass a string of JSON represented data, only the root level (no nested chunks) is stored. Also there exists a limit of 75 total characters passed in eventValue.

 

Prototype:

 

Sample Code:

You can call the tracking method from anywhere in your application. It is called by accessing it through the application’s delegate.

 

NOTE: Import your app delegate’s header file at the top of the file from which you call this method.

NOTE: In the example below, “Detail View” and “product list” are just examples for a particular scenario. Say an app has a bunch of items listed in a UITableView (like the Settings app on the iPhone). The user taps on one of the items in the list to go to a more detailed view. So the you want to log that the user went to the more detailed view of the product list (which was the item on the table table they tapped on). You might sent this pair of events to indicate the user went to a “Detail View” of the “product list”.

 


Sending Spatial Events

Spatial events allow sending a title and an x, y, and z coordinate to our server for visualizing your data.

 

A spatialEvent may be called at any time.


IdentityLink

IdentityLink events provide the opportunity to “link different identities” together. For example, you may have assigned each user of your app an internal userid which you want to connect to a user’s service identifier. Using the IdentityLink method, you can send both your internal id and their service identifier and connect them in the Kochava database.

Kochava reports can be output to show additional identity information for devices in the Kochava database so that you can supplement your reports with internal identifiers that are useful to you and your application.

Although you can call the identityLink method any time, it is best called just once per data pair being connected and it is your responsibility to know you have or have not made that connection.

 


Deep Linking

Pass deep link events to Kochava using this method.  After receiving the URI from your application via openURL:(NSURL *)url sourceApplication: in your application delegate, just pass the url and sourceApplication parameters to the sendDeepLink method. You can learn more about deep linking for iOS here.

 

Starting with iOS 9, Apple’s Universal Links may be used.

If Universal Links are being used, the URL scheme will need to be registered.


Attribution Data Request (Onboarding Links)

Attribution data can be received from Kochava server, usually in less than 10 seconds from the initial application launch. You can receive attribution by a delegate to your host app, by asking for the attribution data at any point, or both. You MUST request attribution data from the server when you initialize the library for either of these approaches to work.

 

If you wish to receive attribution via a delegate, make sure you set the kochavaTracker.trackerDelegate after initializing the library.

 

To receive attribution data via a callback, add the following handler to your application:

 

If you want to ask what attribution data has been retrieved from the server, at any time you can call the getAttributionData method.

 

Sample Payload:

 

With either approach, an NSDictionary will contain the attribution data.

 

Possible return values for the attribution NSDictionary:

  • nil – Either you didn’t indicate when you initialized that you would like to retrieve attribution, or attribution hasn’t yet been determined.  Kochava attempts to determine attribution within the first several seconds after the application has been run the first time.
  • Contains a single key/value pair with attribution = false – represents an organic install.
  • Contains a NSDictionary with a variety of attribution information – indicate attribution was made and contains the details of that attribution.

 

The delegate approach will not return until attribution has been determined and will not return a nil.


Kochava Device ID Retrieval

To retrieve the Kochava Device ID from the SDK, call the following static method (if a Kochava Device ID has not yet been generated it will return an empty string):


Swift Support

The Kochava tvOS SDK supports the Swift programming language through bridging. You will need to add the following to your Objective-C bridging header file.

 

Information on Objective-C / Swift bridging can be found here: https://developer.apple.com/library/ios/documentation/swift/conceptual/buildingcocoaapps/MixandMatch.html.

 

At the top of your AppDelegate class, make sure the following line exists before any class prototypes:

 

If you want to retrieve attribution from the server, you will also need to add this protocol conformance to your tracker’s parent class:

 

You may now use the Kochava Objective-C SDK methods.  For example, you could now initialize the SDK with this:

 

Post-install events can be called with this:

 

To retrieve attribution back from the server, in addition to setting the retrieveAttribution flag above, the following function would receive the data into your application:


Files for Download


Testing the Integration

For more information on testing the integration with Kochava, refer to our Testing an Integration with Kocahva support documentation.

 
 

Last Modified: Jun 27, 2017 at 6:22 am