Support Home > SDK Integration > iOS – SDK Integration

iOS – SDK Integration

The Kochava iOS SDK is lightweight and can be easily integrated. The entire process takes less than 5 minutes, and simply requires adding the SDK to your project and then starting an instance of class KochavaTracker. If you have already integrated the SDK and started the tracker, please visit Using the SDK and choose a topic.

Integrating the SDK


  • Xcode 11.3.1


Supported Platforms:

  • iOS
  • tvOS
  • watchOS


IMPORTANT NOTE: As of 3.16.0 released on 04/08/2020 the SDK is modular. If you have installed a previous version, please take the time to review the integration steps below.


Estimated Time to Complete
7 Minutes
  1. Add the SDK into your project.
  2. In order to use the Kochava SDK, first add it to your project. This can be accomplished using Cocoapods or by downloading the SDK files manually and adding them to your project.


    Using Cocoapods —

    Install one of the following Pods:

    iOS tvOS




    Direct Download —

    Download the zip file and add the contents to your project.

    iOS tvOS


    Release Notes —

    Latest Release Notes


    The Kochava SDK is modular, providing you with the ability to choose which features you want to integrate and use. For a typical Kochava Tracker integration, you need only include the Core and Tracker modules. Other modules may be added depending on your needs.

    1. Download the zip file for the selected SDK, along with the zip file for the single dependent module KochavaCore (if you have not done so already). For a complete list of all modules available for direct download see iOS / tvOS. It is important to always download current versions of each module which you choose to integrate so that compatibility is ensured.
    2. Extract the contents, and copy the included files into your project’s folder using Finder. You may add these files to your project under a sub-folder named Kochava.
    3. Right-click on your project in Xcode, select Add Files to (project name), and then select the files to add to your project.
    4. If you are working with multiple targets, you will want to ensure that you have included each of the included file(s) in the desired targets by selecting each file and reviewing its target membership in the inspector, which appears on the right side in Xcode.
    5. Ensure that the included static libraries (or frameworks) are included in Linked Frameworks and Libraries in your Project (located under the General tab). These will normally have been added at the moment you added the files to your target. If you are using an SDK which is distributed as a framework, you will need to include the frameworks in both the Embedded Binaries as well as Linked Frameworks and Libraries.
    6. Be aware that there are other frameworks that this SDK requires. With the current version of Xcode, and with the default build settings, you generally do not need to add these frameworks manually to your Linked Frameworks and Libraries. But if you’ve disabled automatic linking, then you may also need to add the following frameworks:
      • Foundation
      • UIKit
      • AVFoundation
      • AdSupport
      • CoreGraphics
      • CoreLocation
      • CoreTelephony
      • iAd
      • SystemConfiguration
      • WebKit


  3. Import the SDK’s main header file
  4. The current iOS SDK is natively written in Objective-C. You must import the main header file in order to access its symbols. If you are working in a project which contains Swift code, you must import this file in the Objective-C Bridging Header. For more information, see the Apple page Migrating your Objective-C Code to Swift.


    Sample Code:

Starting the Tracker

Estimated Time to Complete
1 Minute

Once you have added the Kochava SDK to your project, the next step is to configure and start an instance of class KochavaTracker in code. Only your App GUID is required to start the tracker with the default settings, which is the case for typical integrations.

We recommend starting the tracker in the method within your AppDelegate that is called when your application did finish launching, although it can be done elsewhere if needed. Starting the tracker as early as possible will provide more accurate session reporting and help to ensure the tracker has been started before using it. Keep in mind the tracker can only be configured and started once per launch.


Start the Shared Instance with Default Settings (recommended):


We also recommend that you use the provided shared instance of the tracker, rather than creating your own tracker instance. By doing so you won’t need to create or retain the instance yourself. In this documentation we’ll always use the provided shared instance of the tracker and reference it by KochavaTracker.shared. If you create your own instance you’ll simply reference it directly in place of KochavaTracker.shared. Creating multiple trackers is possible by specifying a unique storage identifier, but it is not otherwise recommended and may result in duplicate data or otherwise unintended results if used improperly.


Create Your Own Instance of the Tracker:


Developer API Reference:

constant kKVAParamAppGUIDStringKey
func configure(withParametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)
init?(parametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)

Confirm the Integration

After integrating the SDK and adding the code to start the tracker, launch and run the app for at least 10 seconds or more. During this time the tracker will start and send an install payload to Kochava. To confirm integration was successful, visit the app’s Install Feed Validation page Apps & Assets > Install Feed Validation. On this page you should see one of two integration messages, indicating integration success or failure.


Integration Successful:

 Integration Success!


Along with this message you will also see a variety of data points associated with the device used for testing. At this point your integration is successful and you can proceed to the next step(s).

NOTE: It may take a few minutes for the first install to appear within the Install Feed Validation page. If you do not see this message immediately, you may simply need to wait a few minutes and check again.

Integration Not Complete:

 Integration Not Complete!


If you encounter this message, please review the integration steps, uninstall and reinstall the app, and check again.



SDK WAYPOINT: At this point basic integration is complete and the Kochava SDK will begin reporting session activity and attributing installs.


Where to Go From Here:

Now that you have completed integration you are ready to utilize the many features offered by the Kochava SDK. Continue on to Using the SDK and choose a topic.

Custom Tracker Configuration

If you would like to make adjustments to the tracker configuration beyond the default settings, set your App GUID and the desired parameters in your dictionary, and then pass it to the tracker’s configuration method.


Starting the Shared Instance Using a Custom Configuration:


Creating Your Own Instance Using a Custom Configuration:

Below is a list of all configuration options and their default settings. Keep in mind that in a typical integration these configuration settings should not be adjusted from their default values.

Default — None

This string should be set to your Kochava App GUID, which can be found in your Edit App page within the Kochava dashboard. This value is always required (unless a Partner Name is set).

Default — Disabled

You can be notified of attribution results from Kochava servers. This is not necessary unless you wish to parse the attribution results for use within the app. To do this, pass in the parameter to indicate you wish to retrieve attribution. Also pass in a delegate, and implement the method which is called when the tracker did retrieve an attribution dictionary. Your delegate’s class must be labeled as conforming to the protocol KochavaTrackerDelegate.

For complete details and examples, see: Retrieving Attribution

Default —

Set this value to the desired Log Level to be used by the SDK for debugging purposes.

For complete details and examples, see: Enabling Logging.

Default — false

If you wish to limit ad tracking at the application level, with respect to Kochava conversions, set this value to false. It can also be toggled after starting the tracker using the method to set the app limit ad tracking boolean.

For complete details and examples, see: App Limit Ad Tracking.

Default — None

This is a reserved parameter and should not be set unless provided by your Client Success Manager.

Default — False

Set this value to true if you wish to start the tracker in Sleep mode. This advanced feature prevents the tracker from sending any network transactions and delays collection of the install data until woken.

For complete details and examples, see: Sleeping the Tracker

Default — False
As GDPR compliance can present many challenges during development, Kochava offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Management feature. By using this feature the Kochava SDK will handle determining when consent is required for any user while shouldering much the GDPR burden for you.

NOTE: This is an advanced feature requiring additional setup within your Kochava dashboard and should not be enabled without a full and complete understanding of how to use the Intelligent Consent Management feature.

For complete details and examples, see: Intelligent Consent Management.

Migration Guide

If you are migrating from a Kochava SDK version prior to version 3.0.0 (typically prior to 2017) please follow the migration steps outlined in the Migration Guide before proceeding with integrating the current SDK.