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 3 minutes, and simply requires adding the SDK to your project and then starting the tracker. If you have already integrated the SDK and started the tracker, please visit Using the SDK and choose a topic.

 

Developing Document: This is a dynamic document that will be updated as Kochava adjusts to changes and updates that come from Apple.

Integrating the SDK

Requirements:

  • Xcode 12 (v4)
  • Xcode 11.3.1 (v3 legacy)

 

Supported Platforms:

  • iOS
  • tvOS
  • watchOS (v4)
  • macCatalyst (v4)
  • maOS (v4)

 

Supported Extensions:

  • Messages
  • Notification Content
  • Notification Service

 

SDK v4 Integration:

v4 of the Kochava Tracker SDK adds support for new features exclusive to iOS 14 such as AppTrackingTransparency and SKAdNetwork v2. Follow these steps if you are ready to begin leveraging these new OS 14 features using our v4 SDK. Otherwise, you may still integrate v3 (legacy) below this section.

Estimated Time to Complete
2 Minutes

The v4 Kochava SDK is distributed as either an XCFramework or static library which you must add to your project.

  • Module iOS tvOS
    KochavaTracker
    Attribution, event tracking, and analytics.

    Version

    Version
    KochavaAdNetwork (optional)
    SKAdNetwork support.

    Version

     

    How to add a Cocoapod:

    If this is your first time adding a Cocoapod, follow these steps for each of the modules above you wish to add:

    1. Open your Podfile in an editor. If you do not have a Podfile yet, see Using Cocoapods.
    2. Add the module, and configure the version to the desired major version. Currently you should use 4. Example:

      3.  

    3. Import the module where you are going to use it. For Swift, you should add this import to your Objective-C Bridging Header.

      4.  

      At this point the v4 SDK integration is complete! When viewing code samples throughout our support site, always choose either Swift v4 or Objective-C v4 code samples. If you have previously integrated v3 of the SDK, please review the migration steps below.

  • Module Direct Download
    KochavaCore
    Core SDK functionality.

    Version
    KochavaTracker
    Attribution, event tracking, and analytics.

    Version
    KochavaAdNetwork (optional)
    SKAdNetwork support.

    Version

     

    How to Add a Direct Download:

    Follow these steps for each of the modules above you wish to add:

    1. Download either the XCFramework or static library zip file from the link above and add the contents to your project. We strongly recommend integrating the XCFramework rather than the static library.
      1. Extract the contents, and copy the included files into your project’s folder using Finder. You will typically want to add these files to the root folder of your project.
      2. Right-clicking on your project in Xcode, select “Add Files to (project name)” and the included files to your project.
      3. 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.
      4. Ensure that the included framework (or static library) is included in Frameworks, Libraries, and Embedded Content in your project target (located under the General tab). It will normally have been added at the moment you added the file to your target.

       

    2. Import the SDK’s main header file.
      The current Apple SDK is natively written in Objective-C. You must import the main header file in order to access its symbols. If you’re using static libraries and you’re 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:

    Framework, Swift —

     

    Framework, Objective-C —

     

    Static Library, Objective-C —

  • VERSION NOTE: Requires Xcode 12.2 or higher. Swift Package Manager first became available in Xcode 12.0, but did not function comprehensively until Xcode 12.2.

     

    Module Swift Package
    KochavaCore
    Core SDK functionality.     		https://github.com/Kochava/Apple-SwiftPackage-KochavaCore
    KochavaTracker
    Attribution, event tracking, and analytics.     		https://github.com/Kochava/Apple-SwiftPackage-KochavaTracker
    KochavaAdNetwork (optional)
    SKAdNetwork support.     		https://github.com/Kochava/Apple-SwiftPackage-KochavaAdNetwork
    KochavaEngagementExtension (optional)
    Push notification service and content extension support.     		https://github.com/Kochava/Apple-SwiftPackage-KochavaEngagementExtension

    Migrating from Version 3 of the SDK:

    If you are migrating to XCFrameworks or Swift Package Manager and had previously been using an earlier version of the Kochava SDK, the process to migrate your code includes searching for any previous imports of KochavaTracker.h and replacing them using import KochavaTracker (or #import <KochavaTracker/KochavaTracker.h>  for Objective-C). When inside of an Objective-C bridging header these imports should be removed.

    If you were using Cocoapods, you should remove KochavaTracker from your podfile.

    If you integrated a direct download of the SDK you should move the associated files from your project into the trash.

    Once you have removed the previous SDK you will encounter build errors due to some API changes associated with v4. Newer APIs generally remain the same, whereas older APIs have been modernized.

     

    How to add a Swift Package:

    If this is your first time adding a Swift Package, follow these steps for each of the modules above you wish to add:

    1. Copy the URL of the swift package to your pasteboard.
    2. In Xcode 12.2 or higher, go to File > Swift Packages > Add Package Dependency.
    3. Paste in the URL of the swift package into the prompt.
    4. Configure the version to the desired major version. Currently you should use 4.

     

    At this point the v4 SDK integration is complete! When viewing code samples throughout our support site, always choose either [Swift v4] or [Objective-C v4] code samples. If you have previously integrated v3 of the SDK, please review the migration steps below.

    It is important to perform a clean build whenever building for a new version of our SDK (Command – Shift – K). Apple’s package management system (as of Xcode 12 Beta 6) does not automatically recognize the packages have changed.

     

An overview of API Changes from v3 to v4—

  1. class KochavaTracker was renamed to KVATracker. You will want to search and replace all references, but not those which are associated with the module, such as import statements. The name of the module remains KochavaTracker.
  2. The API to start an instance of class KVATracker has now been simplified and no longer uses a parameters dictionary. If you were passing parameters other than an app guid or partner name, you will find setters you can use to set these parameters directly. To configure the log level, instead set KVALog.shared.level.
  3. If you were setting a storage identifier on the shared instance, you will find a new static variable which you can set prior to accessing the shared instance.
  4. Events are sent by using class KVAEvent directly. This includes the convenience methods for sending an event, which are now located there. See KVAEvent+Standard.h.

Estimated Time to Complete
7 Minutes

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.

 

Follow the steps below to integrate v3 (legacy) of the Kochava Tracker SDK. v3 lacks support for iOS 14 exclusive features such as AppTrackingTransparency and SKAdNetwork v2. If you require support for these iOS 14 features please use v4 above.

 

  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 —

    NOTE: In order to use version 3 of the SDK, you should configure your podfile with a version ~> 3 .

    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

     

  2. Import the SDK’s main header file

    3. 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:

trackerParametersDictionary
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 — LogLevel.info

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) to version 3.x, please follow the migration steps outlined in the Migration Guide before proceeding with integrating version 3.x.

Migrating from version 3.x to 4.x is simply a matter of reviewing the code samples for any given topic, as the overall usage of the SDK remains the same.