Integrating the SDK
Requirements:
- Xcode 12.4 or higher
Supported Platforms:
- iOS
- tvOS
- watchOS
- macCatalyst
- macOS
Supported Extensions:
- Messages
- Notification Content
- Notification Service
Data Privacy:
Version 5 Integration:
The v5 Kochava SDK is distributed as either an XCFramework or static library which you must add to your project. A typical integration includes modules KochavaCore, KochavaTracker, and KochavaAdNetwork. If upgrading from v4 to v5 of the SDK, note that the integration process is unchanged. Swift Packages is the preferred distribution method, but other options are available.
Module Swift Package Module is Optional
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
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.https://github.com/Kochava/Apple-SwiftPackage-KochavaAdNetwork ✔ KochavaEngagementExtension
Push notification service and content extension support.https://github.com/Kochava/Apple-SwiftPackage-KochavaEngagementExtension ✔ 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:
- Copy the URL of the swift package to your pasteboard.
- In Xcode 12.2 or higher, go to File > Swift Packages > Add Package Dependency.
- Paste in the URL of the swift package into the prompt.
- Configure the version to the desired major version. Currently you should use
.
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.
IMPORTANT NOTE: The Swift Standard Libraries started being bundled into the operating system beginning in iOS 12.2. If your minimum deployment target is earlier than this, then the host app’s project must have the switch for Always Embed Standard Libraries turned on. At this point the v5 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.
Cocoapods wrapping XCFrameworks:
Module Cocoapod Module is Optional
KochavaTracker
Attribution, event tracking, and analytics.Apple-Cocoapod-KochavaTracker
KochavaAdNetwork
Support for SKAdNetwork. This module
is required for integrations which intend
to leverage Apple’s SKAdNetwork support.Apple-Cocoapod-KochavaAdNetwork
✔
Cocoapods wrapping Static Libraries:
Module iOS tvOS Module is Optional
KochavaTracker
Attribution, event tracking, and analytics.KochavaTrackeriOS KochavaTrackerTVOS KochavaAdNetwork
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.KochavaAdNetworkiOS ✔ 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:
- Open your Podfile in an editor. If you do not have a Podfile yet, see Using Cocoapods.
- Add the module, and configure the version to the desired major version. Currently you should use 5.
Example:
1234target 'MyApp' dopod 'Apple-Cocoapod-KochavaTracker', '~> 5.0'pod 'Apple-Cocoapod-KochavaAdNetwork', '~> 5.0'endSample Code:
XCFramework(s), Swift —
12import KochavaTrackerimport KochavaAdNetwork // optionalXCFramework(s), Objective-C —
12#import <KochavaTracker/KochavaTracker.h>#import <KochavaAdNetwork/KochavaAdNetwork.h> // optionalStatic Library(s), Objective-C —
12#import "KochavaTracker.h"#import "KochavaAdNetwork.h" // optionalAt this point the v5 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 XCFramework Module is Optional
KochavaCore
Core SDK functionality.KochavaTracker
Attribution, event tracking, and analytics.KochavaAdNetwork
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.✔ How to add an XCFramework:
Follow these steps for each of the modules above you wish to add:
- Download the XCFramework from the link above and add it to your project.
- Download the release archive containing the XCFramework.
- Open the archive and copy the XCFramework into your Xcode project folder using Finder. You will typically want to add this file to the Frameworks folder of your project.
- Right click on your project in Xcode, select Add Files to (project name), and add the included file to your project.
- If you are working with multiple targets, you will want to ensure that you have included the XCFramework in each of the desired targets by selecting the file and reviewing its target membership in the inspector, which appears on the right side in Xcode.
- Ensure that the XCFramework 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.
- Import the XCFramework.
XCFramework Addition Details:
Expand for Details
Sample Code:
XCFramework(s), Swift —
12import KochavaTrackerimport KochavaAdNetwork // optionalXCFramework(s), Objective-C —
12#import <KochavaTracker/KochavaTracker.h>#import <KochavaAdNetwork/KochavaAdNetwork.h> // optionalModule iOS Static Library tvOS Static Library Module is Optional
KochavaCore
Core SDK functionality.KochavaTracker
Attribution, event tracking, and analytics.KochavaAdNetwork
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.✔ How to add a Static Library:
Follow these steps for each of the modules above you wish to add:
- Download the static library from the link above and add it to your project. We recommend integrating XCFrameworks rather than static libraries.
- Download the release archive containing the static library.
- Open the archive and copy the static library (including the folder wrapping it with the headers) into your Xcode project folder using Finder. You will typically want to add this to the root folder of your project, and we recommend placing it under a sub-folder named Kochava.
- Right click on your project in Xcode, select Add Files to (project name), and the included files to your project.
- If you are working with multiple targets, you will want to ensure that you have included the static library in each of the desired targets by selecting associated files and reviewing their target membership in the inspector, which appears on the right side in Xcode.
- Ensure that the included 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.
- Import the static library’s main header file.
The Kochava 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 your Objective-C Bridging Header. For more information, see the Apple page Migrating your Objective-C Code to Swift.:
Static Library Addition Details:
Expand for Details
Sample Code:
Static Library(s), Objective-C —
12#import "KochavaTracker.h"#import "KochavaAdNetwork.h" // optional
An overview of API Changes from v3 to v4—
- 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.
- 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.
- 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.
- 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.
Starting the Tracker
Once you have added the Kochava SDK to your project, the next step is to configure and start an instance of class KVATracker 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):
-
123456import KochavaTrackerfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {KVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")return true}
-
123456#import <KochavaTracker/KochavaTracker.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];return YES;}
-
123func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {KVATracker.shared.configure(withParametersDictionary: [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"], delegate: nil)}
-
1234- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {[KVATracker.shared configureWithParametersDictionary:@{kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_"} delegate:nil];return YES;}
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 will always use the provided shared instance of the tracker and reference it by KVATracker.shared. If you create your own instance you’ll simply reference it directly in place of KVATracker.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:
-
123// start your own instance of class KVATrackerlet tracker = KVATracker()tracker.start(withAppGUIDString: "_YOUR_APP_GUID_")
-
123// start your own instance of class KVATrackerKVATracker *tracker = [KVATracker tracker];[tracker startWithAppGUIDString:@"_YOUR_APP_GUID_"];
-
12// start your own instance of class KochavaTrackerlet tracker = KochavaTracker(parametersDictionary: [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"], delegate: nil)
-
12// start your own instance of class KochavaTrackerKochavaTracker *tracker = [[KochavaTracker alloc] initWithParametersDictionary:@{kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_"} delegate:nil];
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:
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:
If you encounter this message, please review the integration steps, uninstall and reinstall the app, and check again.
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:
-
12345// KVALogKVALog.shared.level = .never// KVATracker.sharedKVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")
-
12345// KVALogKVALog.shared.level = KVALogLevel.never;// KVATracker.shared[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];
-
123456789101112func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"]// KVATracker.sharedKVATracker.shared.configure(withParametersDictionary: parametersDictionary, delegate: nil)}
-
12345678// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_"};// KVATracker.shared[KVATracker.shared configureWithParametersDictionary:parametersDictionary delegate:nil];
Creating Your Own Instance Using a Custom Configuration:
-
123456// KVALogKVALog.shared.level = .never// trackerlet tracker = KVATracker()tracker.start(withAppGUIDString: "_YOUR_APP_GUID_")
-
123456// KVALogKVALog.shared.level = KVALogLevel.never;// trackerKVATracker *tracker = [KVATracker tracker];[tracker startWithAppGUIDString:@"_YOUR_APP_GUID_"];
-
12345678// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"]// trackerlet tracker = KochavaTracker(parametersDictionary: parametersDictionary, delegate: nil)
-
12345678// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_"};// trackerKochavaTracker *tracker = [[KochavaTracker alloc] initWithParametersDictionary:parametersDictionary delegate:nil];
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).
-
1KVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")
-
1/[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];
-
12var parametersDictionary: [AnyHashable: Any] = [:]parametersDictionary[kKVAParamAppGUIDStringKey] = "_YOUR_APP_GUID_"
-
12NSMutableDictionary *parametersDictionary = NSMutableDictionary.dictionary;parametersDictionary[kKVAParamAppGUIDStringKey] = @"_YOUR_APP_GUID_";
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.
-
12345678910111213141516class AppDelegate: UIResponder, UIApplicationDelegate{func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {// KVATracker.sharedKVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")KVATracker.shared.attribution.retrieveResult{(attributionResult) inprint("do something with attributionResult... \(attributionResult.kva_asForContextObject(withContext: .log) as! [AnyHashable: Any])")}return true}}
-
123456789101112131415- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {// KVATracker.shared[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];[KVATracker.shared.attribution retrieveResultWithCompletionHandler:^(KVAAttributionResult * _Nonnull attributionResult){// ...}];return YES;}//
-
123456789101112131415161718class AppDelegate: UIResponder, UIApplicationDelegate, KochavaTrackerDelegate{func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_",kKVAParamRetrieveAttributionBoolKey: true]// KVATracker.sharedKVATracker.shared.configure(withParametersDictionary: parametersDictionary, delegate: self)}func tracker(_ tracker: KochavaTracker, didRetrieveAttributionDictionary attributionDictionary: [AnyHashable : Any]) {print("do something with attributionDictionary... \(attributionDictionary)")}}
-
123456789101112131415161718192021222324@interface AppDelegate () <KochavaTrackerDelegate>@end@implementation AppDelegate- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_",kKVAParamRetrieveAttributionBoolKey: @(YES)};// KVATracker.shared[KVATracker.shared configureWithParametersDictionary:parametersDictionary delegate:self];// returnreturn YES;}-(void)tracker:(KochavaTracker *)tracker didRetrieveAttributionDictionary:(NSDictionary *)attributionDictionary {NSLog(@"do something with attributionDictionary... %@", attributionDictionary);}@end
Default — None
Pass each identity link key/value pair which is known when starting the tracker in a dictionary. Identity Links can also be set after starting the tracker using the instance method to send an identity link with a dictionary.
-
1234// KVATracker.sharedKVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")KVATracker.shared.identityLink.register(withNameString: "User ID", identifierString: "123456789")KVATracker.shared.identityLink.register(withNameString: "Login", identifierString: "ljenkins")
-
1234// KVATracker.shared[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];[KVATracker.shared.identityLink registerWithNameString:@"User ID" identifierString:@"123456789"];[KVATracker.shared.identityLink registerWithNameString:@"Login" identifierString:@"ljenkins"];
-
1234567891011121314// identityLinkDictionarylet identityLinkDictionary: [AnyHashable: Any] = ["User ID": "123456789","Login": "ljenkins"]// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_",kKVAParamIdentityLinkDictionaryKey: identityLinkDictionary]// KVATracker.sharedKVATracker.shared.configure(withParametersDictionary: parametersDictionary, delegate: nil)
-
1234567891011121314// identityLinkDictionaryNSDictionary *identityLinkDictionary = @{@"User ID": @"123456789",@"Login": @"ljenkins"};// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_",kKVAParamIdentityLinkDictionaryKey: identityLinkDictionary};// KVATracker.shared[KVATracker.shared configureWithParametersDictionary:parametersDictionary delegate:nil];
For complete details and examples, see: Identity Linking.
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.
-
1KVATracker.shared.consent.intelligentManagementBool = true
-
1KVATracker.shared.consent.intelligentManagementBool = YES;
-
1KVATracker.shared.consent.intelligentManagementBool = true
-
1KVATracker.shared.consent.intelligentManagementBool = YES;
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.
