Migrate to Adobe Experience Platform 5.x SDKs for iOS

This Mobile SDK version for iOS now supports a minimum iOS version of 12.0 and a tvOS version of 12.0. The XCFrameworks included in the GitHub release are built using Xcode 15.0.

SDK versions

Extension	Version
Mobile Core
Rules Engine
Signal
Identity
Lifecycle
Profile
Adobe Experience Platform Assurance
Adobe Experience Platform Edge Network
Identity for Edge Network
Consent for Edge Network
Media for Edge Network
Edge Bridge
Adobe Journey Optimizer
Adobe Journey Optimizer - Decisioning
Places Service
Adobe Analytics
Adobe Analytics - Media Analytics for Audio & Video
Adobe Target
Adobe Campaign Standard
Adobe Campaign Classic
Adobe Audience Manager

Migrate from Adobe Experience Platform 4.x SDKs for iOS

If you have implemented Adobe Experience Platform 4.x SDKs for iOS, then this guide will help you understand the steps required to migrate your implementation to the Experience Platform 5.x SDKs. In summary, you'll need to:

Update dependencies

Manual library import

If you are importing SDK libraries manually, make sure to update your libraries by downloading the most recent 5.x binaries from their respective Github repositories.

CocoaPods

If you are using CocoaPods to manage your Adobe Experience Platform Mobile SDK dependencies, the following example shows you how to update to Experience Platform 5.x SDKs in your Podfile.

# Update pod dependencies to 5.x version
# pod 'AEPCore', '~> 4.0'
# pod 'AEPLifecycle', '~> 4.0'
# pod 'AEPIdentity', '~> 4.0'
# pod 'AEPSignal', '~> 4.0'
# pod 'AEPUserProfile', '~> 4.0'

  pod 'AEPCore', '~> 5.0'
  pod 'AEPLifecycle', '~> 5.0'
  pod 'AEPIdentity', '~> 5.0'
  pod 'AEPSignal', '~> 5.0'
  pod 'AEPUserProfile', '~> 5.0'
Copied to your clipboard
# Update pod dependencies to 5.x version
# pod 'AEPCore', '~> 4.0'
# pod 'AEPLifecycle', '~> 4.0'
# pod 'AEPIdentity', '~> 4.0'
# pod 'AEPSignal', '~> 4.0'
# pod 'AEPUserProfile', '~> 4.0'

  pod 'AEPCore', '~> 5.0'
  pod 'AEPLifecycle', '~> 5.0'
  pod 'AEPIdentity', '~> 5.0'
  pod 'AEPSignal', '~> 5.0'
  pod 'AEPUserProfile', '~> 5.0'

Save the Podfile, and run pod repo update to update your local CocoaPods repository.

Once the previous command is complete, run pod install or pod update to update the application dependencies.

Swift Package Manager

If you are using Swift Package Manger (SPM) for managing your app dependencies, you can now include the Experience Platform 5.x SDKs either through Xcode UI, or by declaring them as dependencies in the Package.swift project file. For more details, follow the guide for managing dependencies using Swift Package Manager.

Handle API migration and breaking changes

When updating to the Experience Platform 5.x SDKs, please take note of the following updates for API references.

Edge Bridge

As of version 5.0.0 of the Adobe Experience Platform Edge Bridge for iOS, the table below shows how the trackAction and trackState parameters map to the data node of the Experience Event sent to the Experience Platform Edge Network. Edge Network automatically maps these data variables to Adobe Analytics without additional server-side configuration. If you are using Edge Bridge version 4.x and mapping data to XDM in your datastream, adjustments are required for version 5.0.0.

Data	Key path in v4.x	Key path in v5.+	Description
Action	`data.action`	`data.__adobe.analytics.linkName`	As of v5, set as the custom link name in the Analytics hit. The field `data.__adobe.analytics.linkType` with value `other` is also automatically included.
State	`data.state`	`data.__adobe.analytics.pageName`	As of v5, set as the page name in the Analytics hit.
Context data	`data.contextdata`	`data.__adobe.analytics.contextData`	Context data is a map which includes the custom keys and values specified in the `trackAction` and `trackState` API calls.
Context data prefixed with "&&"	`data.contextdata`	`data.__adobe.analytics`	Before v5, there was no special handling of context data prefixed with "&&". As of v5, context data keys prefixed with "&&" are automatically mapped to Analytics variables and no longer include the "&&" prefix. For example, the key `&&products` is sent as `data.__adobe.analytics.products`. Please note that these keys must be known to Analytics and are case sensitive. Find the full list of supported Analytics variables here.
App identifier	Not included	`data.__adobe.analytics.contextData.a.AppID`	As of v5, the application identifier is automatically added to every tracking event under the key name `a.AppID`.
Customer perspective	Not included	`data.__adobe.analytics.cp`	As of v5, the customer perspective is automatically added to every tracking event. The values are either `foreground` or `background`.

Track action example

Given the track action call:

MobileCore.track(action: "action name", data: ["key": "value", "&&products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345"])
Copied to your clipboard
MobileCore.track(action: "action name", data: ["key": "value", "&&products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345"])

The resulting Experience Event has the following payload:

{
  "data":{
    "__adobe": {
      "analytics": {
        "linkName": "action name",
        "linkType": "other",
        "cp": "foreground",
        "products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)",
          "key": "value"
        }
      }
    }
  }
}
Copied to your clipboard
{
  "data":{
    "__adobe": {
      "analytics": {
        "linkName": "action name",
        "linkType": "other",
        "cp": "foreground",
        "products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)",
          "key": "value"
        }
      }
    }
  }
}

Track state example

Given the track state call:

MobileCore.track(state: "view name", data: ["&&events": "event5,event2=2"])
Copied to your clipboard
MobileCore.track(state: "view name", data: ["&&events": "event5,event2=2"])

The resulting Experience Event has the following payload:

{
  "data":{
    "__adobe": {
      "analytics": {
        "pageName": "view name",
        "cp": "foreground",
        "events": "event5,event2=2",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)"
        }
      }
    }
  }
}
Copied to your clipboard
{
  "data":{
    "__adobe": {
      "analytics": {
        "pageName": "view name",
        "cp": "foreground",
        "events": "event5,event2=2",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)"
        }
      }
    }
  }
}

Messaging

Push tracking

In order to provide more control over URL handling from UNNotificationResponse objects, two old APIs were removed and a new one was added.

Old API (4.x)	New API (5.x)
`handleNotificationResponse(_:applicationOpened:withCustomActionId:)`	`handleNotificationResponse(_:urlHandler:closure:)`
`handleNotificationResponse(_:closure:)`	`handleNotificationResponse(_:urlHandler:closure:)`

For examples see handleNotificationResponse.