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
Requirements:
- Xcode 9.2
Supported Platforms:
- iOS
- tvOS
- watchOS
Integration:
- Add the SDK into your project.
- 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.
- Right-clicking 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’ve 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.
- Ensure that the included static library (or framework) is included in Linked Frameworks and Libraries in your Project (located under the General tab). It will normally have been added at the moment you added the file to your target. If you are using an SDK which is distributed as a framework, you will need to include the framework in both the Embedded Binaries as well as Linked Frameworks and Libraries.
- 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
- Import the SDK’s main header file
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 —
Download the zip file for the selected SDK.
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’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:
|
1 |
#import “KochavaTracker.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 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):
-
123func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {KochavaTracker.shared.configure(withParametersDictionary: [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"], delegate: nil)}
-
1234- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {[KochavaTracker.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’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:
-
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];
Developer API Reference:
trackerParametersDictionary
constant kKVAParamAppGUIDStringKey
func configure(withParametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)
init?(parametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)
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.
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.
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:
-
123456789101112func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_"]// KochavaTracker.sharedKochavaTracker.shared.configure(withParametersDictionary: parametersDictionary, delegate: nil)}
-
12345678// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamLogLevelEnumKey: kKVALogLevelEnumNone,kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_"};// KochavaTracker.shared[KochavaTracker.shared configureWithParametersDictionary:parametersDictionary delegate:nil];
Creating Your Own Instance Using a Custom Configuration:
-
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).
-
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.
-
123456789101112131415161718class AppDelegate: UIResponder, UIApplicationDelegate, KochavaTrackerDelegate{func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_",kKVAParamRetrieveAttributionBoolKey: true]// KochavaTracker.sharedKochavaTracker.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)};// KochavaTracker.shared[KochavaTracker.shared configureWithParametersDictionary:parametersDictionary delegate:self];// returnreturn YES;}-(void)tracker:(KochavaTracker *)tracker didRetrieveAttributionDictionary:(NSDictionary *)attributionDictionary {NSLog(@"do something with attributionDictionary... %@", attributionDictionary);}@end
For complete details and examples, see: Retrieving Attribution
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.
-
1234567891011121314// identityLinkDictionarylet identityLinkDictionary: [AnyHashable: Any] = ["User ID": "123456789","Login": "ljenkins"]// parametersDictionarylet parametersDictionary: [AnyHashable: Any] = [kKVAParamAppGUIDStringKey: "_YOUR_APP_GUID_",kKVAParamIdentityLinkDictionaryKey: identityLinkDictionary]// KochavaTracker.sharedKochavaTracker.shared.configure(withParametersDictionary: parametersDictionary, delegate: nil)
-
1234567891011121314// identityLinkDictionaryNSDictionary *identityLinkDictionary = @{@"User ID": @"123456789",@"Login": @"ljenkins"};// parametersDictionaryNSDictionary *parametersDictionary = @{kKVAParamAppGUIDStringKey: @"_YOUR_APP_GUID_",kKVAParamIdentityLinkDictionaryKey: identityLinkDictionary};// KochavaTracker.shared[KochavaTracker.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.
-
1KochavaTracker.shared.consent.intelligentManagementBool = true
-
1KochavaTracker.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) please follow the migration steps outlined in the Migration Guide before proceeding with integrating the current SDK.
