iOS – Migrating to v8

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

Estimated Time to Complete
10 Minute

 

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/PathsNew 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 > ContainingWithComments
    import KochavaCoreimport KochavaNetworking
    import KochavaTrackerimport 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.
    KVALogLevelLog.Level
    KVALogLog
    KVATrackerMeasurement
    .start(withAppGUIDString.start(appGUIDString
    KVAEventEvent
    KVAEventTypeEvent_Type
    KVADeeplinkDeeplink
    KVAIdentityLinkIdentityLink
    .deviceId.string.installIdentifier.stringReplacing 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.
    payloadKeyStringArraydatapointKeyArrayThis is a parameter when registering privacy profiles.
    kva_as(forContextto(context
    KVAAppGroupsAppGroups
    deviceAppGroupIdentifiergeneralAppGroupIdentifier
    KVAIn 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.registerCustomIdentifier.register
    KVATracker.shared.customIdentifiers.registerCustomIdentifier.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(withNameStringsendCustom(eventNameYou 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(withTypeevent(type
    Event.customEvent(withNameStringEvent(customWithEventNameThe 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.registerIdentityLink.registerThere 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.registerIdentityLink.registerIf 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.stringReplacing 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.
    sharedStorageIdStringsharedStorageIdentifierIt 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 > ContainingWithComments
    #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.
    KVALogLevelKVALog_Level
    KVATrackerKVAMeasurement
    KVAEventTypeKVAEvent_Type
    retrieveResultWithCompletionHandlerretrieveResultWithClosure_didComplete
    KVAAttributionResultKVAMeasurement_Attribution_Result
    .deviceId.string.installIdentifier.stringReplacing 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.
    payloadKeyStringArraydatapointKeyArrayThis is a parameter when registering privacy profiles.
    deviceAppGroupIdentifiergeneralAppGroupIdentifier

    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:

    sendCustomWithNameStringsendCustomWithNameStringYou 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 registerWithNameStringKVAIdentityLink registerWithNameExpect to need to also replace “identifierString” with “identifier” wherever you find these.
    [tracker.identityLink registerWithNameStringKVAIdentityLink registerWithNameThere 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 registerWithNameKVAIdentityLink registerWithNameIf you are on an even older version, you may need to also remove the word “String” from the parameter names.
    [tracker.identityLink registerWithNameKVAIdentityLink registerWithNameThere 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.stringReplacing 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.
    sharedStorageIdStringsharedStorageIdentifierIt 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.

 
 

Last Modified: Feb 1, 2024 at 4:17 pm