iOS – SDK Integration

The Kochava 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 measurement client. If you have already integrated the SDK, please visit Using the SDK and choose a topic.

INTEGRATION NOTE: Migrating to v8? Refer to our support documentation for existing clients upgrading from earlier versions.

Integrating the SDK

Requirements:

• Xcode 15.2 or higher

Supported Platforms:

• iOS
• macCatalyst
• macOS
• tvOS
• visionOS
• watchOS

Supported Extensions:

• Messages
• Notification Content
• Notification Service

Data Privacy:

• SDK Data Privacy and Safety
• Apple’s Privacy Manifest

Integration:

Estimated Time to Complete
2 Minutes

The Kochava SDK is distributed as Swift Packages. A measurement integration includes modules KochavaNetworking and KochavaMeasurement. A tracking integration includes modules KochavaNetworking, KochavaMeasurement, and KochavaTracking.

The tracking module is optional but must be included if you wish to collect the IDFA following ATT authorization. Otherwise, the tracking module can be omitted from your integration and no IDFA collection will take place by the SDK. Previous versions of the SDK automatically included collection of the IDFA, but this functionality is now optional to align with Apple’s privacy manifest requirements.

Module	Swift Package	Module is Optional
KochavaNetworking Advanced networking support. A foundational module for the Kochava SDK.	https://github.com/Kochava/Apple-SwiftPackage-KochavaNetworking-XCFramework
KochavaMeasurement Measurement of Attribution and Events.	https://github.com/Kochava/Apple-SwiftPackage-KochavaMeasurement-XCFramework
KochavaTracking Adds tracking features for enhanced advertising measurement. Includes the collection and association of the IDFA	https://github.com/Kochava/Apple-SwiftPackage-KochavaTracking-XCFramework	✔

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 .

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

Google On-Device Conversion Measurement

The KochavaGoogleODM SDK supports Google Ads’ on-device conversion measurement using event data when combined with the Google ODM SDK. It is an optional module which extends the KochavaMeasurement SDK.

This module must be included in your integration if you wish to collect the Google Ads conversion info for Integrated Conversion Measurement for App Campaigns. Otherwise, the GoogleODM module can be omitted from your integration and no Google Ads conversion info collection will take place by the SDK.

Optionally add the following to your project:

Import the modules and provide the conversion manager to the KochavaGoogleODM SDK before starting the Measurement SDK.

import GoogleAdsOnDeviceConversion
import KochavaGoogleODM

// ...
 
KochavaGoogleODM.ConversionManager.shared = GoogleAdsOnDeviceConversion.ConversionManager.sharedInstance

// ... Start the KochavaMeasurement SDK

Starting the Measurement Client

Estimated Time to Complete
1 Minute

Once you have added the Kochava SDK to your project, the next step is to configure and start the measurement client. Only your App GUID is required to start the client with the default settings, which is the case for typical integrations.

We recommend starting the client 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 client as early as possible will provide more accurate session reporting and help to ensure the client is actively processing tasks when subsequent requests are made. The call to start the measurement client should be made one time when your application launches.

Start the Shared Instance:

import KochavaNetworking
import KochavaMeasurement
import KochavaTracking  // optional
 
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool 
{
    Log.shared.level = .info

    let measurement = Measurement.shared
    measurement.start(appGUIDString: "_YOUR_APP_GUID_")

    return true
}

@import KochavaNetworking;
@import KochavaMeasurement;
@import KochavaTracking;  // optional
 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
    KVALog.shared.level = KVALog_Level.info;

    KVAMeasurement *measurement = KVAMeasurement.shared;
    [measurement startWithAppGUIDString:@"_YOUR_APP_GUID_"];

    return YES;
}

import KochavaTracker
 
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    KVATracker.shared.start(withAppGUIDString: "_YOUR_APP_GUID_")
    return true
}

Confirm the Integration

After integrating the SDK and adding the code to start the measurement client, launch and run the app for at least 10 seconds or more. During this time the client 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.

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.