Integrating the SDK
Requirements:
- Xcode 14.1 or higher
Supported Platforms:
- iOS
- tvOS
- watchOS
- macCatalyst
- macOS
Supported Extensions:
- Messages
- Notification Content
- Notification Service
Data Privacy:
Integration:
The Kochava SDK is distributed as an XCFramework. A typical integration includes modules KochavaCore and KochavaTracker. 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 (v5)
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.
This optional module was moved into module KochavaTracker in v6 and does not need to be added separately in newer versions.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
.
At this point the Kochava SDK integration is complete! When viewing code samples throughout our support site, always choose either [Swift] or [Objective-C] code samples.
NOTE: It is important to sometimes perform a clean build when building for a new version of our SDK (Command – Shift – K). Apple’s package management system does not always automatically recognize that the packages have been updated
Module Cocoapod Module is Optional
KochavaTracker
Attribution, event tracking, and analytics.Apple-Cocoapod-KochavaTracker
KochavaAdNetwork (v5)
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.
This optional module was moved into module KochavaTracker in v6 and does not need to be added separately in newer versions.Apple-Cocoapod-KochavaAdNetwork
✔ Deprecation Advisory: With the release of version 6.1.1 of the Kochava Apple SDK, the transition from Objective-C to Swift was complete, and we discontinued all static library products in favor of xcframeworks. Please contact support@kochava.com if you have any questions. Modules:
Module iOS tvOS Module is OptionalKochavaTracker
Attribution, event tracking, and analytics.KochavaTrackeriOS KochavaTrackerTVOS KochavaAdNetwork (v5)
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.
This optional module was moved into module KochavaTracker in v6 and does not need to be added separately in newer versions.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 7.
Example:
123target 'MyApp' dopod 'Apple-Cocoapod-KochavaTracker', '~> 7.0'endSample Code:
XCFramework(s), Swift —
1import KochavaTrackerXCFramework(s), Objective-C —
1@import KochavaTracker;At this point the v5 SDK integration is complete! When viewing code samples throughout our support site, always choose either Swift or Objective-C code samples.
Module XCFramework Module is Optional
KochavaCore
Core SDK functionality.KochavaTracker
Attribution, event tracking, and analytics.KochavaAdNetwork (v5)
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.
This optional module was moved into module KochavaTracker in v6 and does not need to be added separately in newer versions.✔ 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 —
1import KochavaTrackerXCFramework(s), Objective-C —
1@import KochavaTracker;Deprecation Advisory: With the release of version 6.1.1 of the Kochava Apple SDK, the transition from Objective-C to Swift was complete, and we discontinued all static library products in favor of xcframeworks. Please contact support@kochava.com if you have any questions. Module iOS Static Library tvOS Static Library Module is Optional
KochavaCore
Core SDK functionality.KochavaTracker
Attribution, event tracking, and analytics.KochavaAdNetwork (v5)
Support for SKAdNetwork. This module is required for integrations which intend to leverage Apple’s SKAdNetwork support.
This optional module was moved into module KochavaTracker in v6 and does not need to be added separately in newer versions.✔ 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
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 is actively processing tasks when subsequent requests are made. The call to start a tracker should be made one time when your application launches.
Start the Shared Instance:
- 123456import KochavaTrackerfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {KVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")return true}
- 123456@import KochavaTracker;- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {[KVATracker.shared startWithAppGUIDString:@"_YOUR_APP_GUID_"];return YES;}
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.
