Overview
Apple SDK version 8.0.0 split SDK KochavaTracker (v7.x and prior) into two separate SDKs, KochavaMeasurement and KochavaTracking.
NOTE: Tracking not Tracker
This reorganization provides a clear separation between the code which is involved in measurement and the code which is involved in tracking, providing the fullest support of Apple’s new Privacy Manifest feature introduced in Xcode 15 and iOS 17.
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.
With a code migration process being required for the host integration, we used this opportunity to make a few additional breaking changes. Module KochavaCore was renamed to KochavaNetworking. This is part of a process where this module is being open-sourced and offered for wider use. Objective-C prefixing using “KVA” was also removed when working in Swift, and only retained when/if working in Objective-C.
For users of previous versions of the Kochava SDK there is an easy pathway to migrate to the new structure provided in version 8. Using the following steps you can be building again in a few minutes.
Migration Steps
Start with v7.4.0:
These instructions assume that you are starting on v7.4.0, and so you should migrate up to that specific version first (assuming you have not already). Along the way there have been improvements to the APIs, along with deprecations which have been added to guide you into the newer APIs. In most cases a deprecation warning with a “Fix” option will be presented which can quickly get you to where you want to be to be ready for the subsequent migration to v8. Most of these deprecations occurred in v7.1.0. If you are already on v7.1.0 or higher you may not need to update to v7.4.0 first, but it may not be a bad idea as there were a few less used API updates. In either case, you will want to make sure any existing deprecation warnings have been resolved before moving forward.
Update Swift Packages:
Replace (remove and add) Swift Packages for the following modules:
| Old Names/Paths | New Names/Paths |
|---|---|
| KochavaCore https://github.com/Kochava/Apple-SwiftPackage-KochavaCore | KochavaNetworking https://github.com/Kochava/Apple-SwiftPackage-KochavaNetworking-XCFramework |
| KochavaTracker https://github.com/Kochava/Apple-SwiftPackage-KochavaTracker | KochavaMeasurement https://github.com/Kochava/Apple-SwiftPackage-KochavaMeasurement-XCFramework |
| KochavaTracking* https://github.com/Kochava/Apple-SwiftPackage-KochavaTracking-XCFramework |
* NOTE: Optional module KochavaTracking is a new module. In order to have the same functionality as you had before with module KochavaTracker (also please note again the difference between “Tracker” (old) and “Tracking” (new)) you should include the new optional KochavaTracking module in addition to modules KochavaNetworking and KochavaMeasurement. If you want to perform measurement only, and not enhance your data using cross-site tracking features, then you may now omit this module. Not including this module most importantly means that the SDK will not collect the IDFA- and the code to do it will not be present.
What if I was using Cocoapods or XCFramework direct downloads?
With version 8 the Apple Kochava SDK is being distributed through Swift Packages exclusively. If you had been using Cocoapods, the process to migrate is to remove any Kochava Cocoapods (KochavaCore, KochavaTracker, KochavaAdNetwork, etc.) from your podfile and add the above Swift Packages to your project’s Settings > Package Dependencies. You will also want to make sure the associated libraries are linked into your target(s). If you had been directly downloading the XCFrameworks, you may continue to do so from the Swift Packages repositories which wrap an .xcframework.
Which version should I be specifying?
You are welcome to use the latest version of the Kochava SDK at the time you are reading this. Using any version after v8.0.0 should be expected to work with these instructions.
Text Find and Replace:
In Xcode, use Find > Find and Replace in Project… (alternatively Find and Replace in Workspace…) to find and replace the following text, one at a time, in the following order, matching case, and taking note of the two language options available (see tab for Objective-C). Extra care will be required if you have a mixed language project, as the two sets to find and replace instructions cannot be applied to files of the other type. Once your project begins building again, and you see no deprecation warnings, you can stop going through the list- as the APIs being updated become less commonly used as you move down:
Replace > Text > Containing With Comments import KochavaCore import KochavaNetworking import KochavaTracker import KochavaMeasurement
import KochavaTrackingThe inclusion of module KochavaTracking here is now an option. Leave it in for equivalent support, or take it out for measurement only support. KVALogLevel Log.Level KVALog Log KVATracker Measurement .start(withAppGUIDString .start(appGUIDString KVAEvent Event KVAEventType Event_Type KVADeeplink Deeplink KVAIdentityLink IdentityLink .deviceId.string .installIdentifier.string Replacing this will get you to the deprecated synchronous getter. From there a deprecation notice will encourage you to use the new asynchronous retrieve function, but the deprecated synchronous function remains available for now. payloadKeyStringArray datapointKeyArray This is a parameter when registering privacy profiles. kva_as(forContext to(context KVAAppGroups AppGroups deviceAppGroupIdentifier generalAppGroupIdentifier KVA In the event there is anything left in Swift code not already addressed, this prefix is being removed, i.e. replaced with nothing. This only applies to Swift. Objective-C code retains many common uses of KVA. Keep this in mind with your find and replace if you have a mixed project which also contains Objective-C. You will not want to remove KVA from Objective-C code in the majority of cases. Deprecated under v7.2.0
The following should already be up to date if you are starting from v7.2.0, but since they were so common we will include them here again just in case:
tracker.customIdentifiers.register CustomIdentifier.register KVATracker.shared.customIdentifiers.register CustomIdentifier.register Deprecated under v7.1.0
The following should already be up to date if you are starting from v7.1.0, but since they were so common we will include them here again just in case:
sendCustom(withNameString sendCustom(eventName You might need to search for this being broken across multiple lines, if you did that. Maybe try also searching just for “sendCustom” and see what you get. event(withType event(type Event.customEvent(withNameString Event(customWithEventName The KVA prefix is presumed to be already taken off at this point. These could be broken up over multiple lines. You may want to also search for just “Event.customEvent(“ and see what you find.
tracker.identityLink.register IdentityLink.register There would be a line above somewhere getting the tracker (the measurement) instance, which you may not need to get anymore. If you are on an even older version, you may need to also remove the word “String” from the parameter names.
KVATracker.shared.identityLink.register IdentityLink.register If you are on an even older version, you may need to also remove the word “String” from the parameter names. link.process(withURL: link.process(url: .deviceIdString .installIdentifier.string Replacing this will get you to the deprecated synchronous getter. From there a deprecation notice will encourage you to use the new asynchronous retrieve function, but the deprecated synchronous function remains available for now. sharedStorageIdString sharedStorageIdentifier It would be unexpected if you were using this, but there will be a few clients who are. Just keep in mind that the using (or especially the changing) of this cannot be done without careful consideration. Replace > Text > Containing With Comments #import
<KochavaCore/KochavaCore.h>#import
<KochavaNetworking/KochavaNetworking.h>#import
<KochavaTracker/KochavaTracker.h>#import
<KochavaMeasurement/KochavaMeasurement.h>
#import
<KochavaTracking/KochavaTracking.h>The inclusion of module KochavaTracking here is now an option. Leave it in for equivalent support, or take it out for measurement only support. @import KochavaCore; @import KochavaNetworking; @import KochavaTracker; @import KochavaMeasurement;
@import KochavaTracking;The inclusion of module KochavaTracking here is now an option. Leave it in for equivalent support, or take it out for measurement only support. KVALogLevel KVALog_Level KVATracker KVAMeasurement KVAEventType KVAEvent_Type retrieveResultWithCompletionHandler retrieveResultWithClosure_didComplete KVAAttributionResult KVAMeasurement_Attribution_Result .deviceId.string .installIdentifier.string Replacing this will get you to the deprecated synchronous getter. From there a deprecation notice will encourage you to use the new asynchronous retrieve function, but the deprecated synchronous function remains available for now. payloadKeyStringArray datapointKeyArray This is a parameter when registering privacy profiles. deviceAppGroupIdentifier generalAppGroupIdentifier Deprecated under v7.2.0
The following should already be up to date if you are starting from v7.2.0, but since they were so common we will include them here again just in case:
[KVATracker.shared.customIdentifiers registerWithName [KVACustomIdentifier registerWithName [tracker.customIdentifiers registerWithName [KVACustomIdentifier registerWithName Deprecated under v7.1.0
The following should already be up to date if you are starting from v7.1.0, but since they were so common we will include them here again just in case:
sendCustomWithNameString sendCustomWithNameString You might need to search for this being broken across multiple lines, if you did that. Maybe try also searching just for “sendCustom” and see what you get. [KVAEvent eventWithType: [[KVAEvent alloc] initWithType: [KVAEvent customEventWithNameString: [[KVAEvent alloc] initCustomWithEventName: [KVATracker.shared.identityLink registerWithNameString KVAIdentityLink registerWithName Expect to need to also replace “identifierString” with “identifier” wherever you find these. [tracker.identityLink registerWithNameString KVAIdentityLink registerWithName There would be a line above somewhere getting the tracker (the measurement) instance, which you may not need to get anymore. Expect to need to also replace “identifierString” with “identifier” wherever you find these.
[KVATracker.shared.identityLink registerWithName KVAIdentityLink registerWithName If you are on an even older version, you may need to also remove the word “String” from the parameter names. [tracker.identityLink registerWithName KVAIdentityLink registerWithName There would be a line above somewhere getting the tracker (the measurement) instance, which you may not need to get anymore. If you are on an even older version, you may need to also remove the word “String” from the parameter names.
[KVADeeplink processWithURL: [KVADeeplink processWithURL: Global find and replace will not fix this, but if you have any of these you may need to replace parameter “completionHandler” with “closure_didComplete”. .deviceIdString .installIdentifier.string Replacing this will get you to the deprecated synchronous getter. From there a deprecation notice will encourage you to use the new asynchronous retrieve function, but the deprecated synchronous function remains available for now. sharedStorageIdString sharedStorageIdentifier It would be unexpected if you were using this, but there will be a few clients who are. Just keep in mind that the using (or especially the changing) of this cannot be done without careful consideration.
Resolve any Deprecation Warnings:
In a few cases there will be some APIs which build but are deprecated. This means you can continue to use them at this time if you want, but it is recommended that you inspect the recommended replacement options and implement them.
As one example, the .installIdentifier.string (formerly .deviceId.string) has a new asynchronous API that we’re moving people toward (and away from the synchronous API). At the present time there aren’t any downsides to the synchronous API and you are welcome to continue using it for now.
Resolving Exceptions / Remaining Build Issues
The above instructions were intended to address most integrations, in particular if you are upgrading from v7. There may be some edge cases where more advanced functions or undocumented features may not be addressed by this documentation. Many of those questions can be answered by referring to our Using the SDK documentation, under the related topic, which includes current sample code.
If you are working in Objective-C you may also miss catching some items if they’re formatted with Objective-C’s non-modern syntax. One example would be “[deviceId string] instead of “deviceId.string”, but other examples would apply. Our find and replace expressions were based on what we had previously recommended doing in our sample code.
Finally, when coming from older legacy versions you may find types like “String” added onto the end of parameters which were optimized out when Swift typealiases were added. So if something isn’t building and you see a term like “String” on the end of a parameter, try removing it and there’s a good chance that will address the issue.
Please also feel free to reach out to your client success manager if you have any questions.
