search
Ctrlk

iOS

What to change in your app when moving the IMS iOS SDK from 1.29.x to 2.0.x.

hashtag
Migration Guide (iOS 1.29.x → 2.0.x)

Sections are ordered for a typical integration.

1

hashtag
Platform and Build

  • Minimum deployment target iOS 15.

  • Build with Xcode 26 or newer. The 2.0.x artifacts are produced with that toolchain.

2

hashtag
Initialization

Remove these arguments from initialize(...):

  • configRegion

  • configEnvironment

Also remove any code that depends on region or environment from the SDK.

3

hashtag
Identity - drop apiKey

apiKey is no longer part of the IMS public API. Stop persisting or accessing it through Identity.

// Before
let identity = Identity(apiKey: apiKey, externalReferenceID: userId)
// After
let identity = Identity(externalReferenceID: userId)
4

hashtag
Logging in a user

circle-info

On top of the API change, there is a one-time step required for already-logged-in users on first run after upgrade — see One-time upgrade step below.

Replace completion-handler usage with async / await and Result.

In 2.0.x the SDK persists identity across launches. Call setIdentity() once, on login success.

On .failure, the user is not signed in to the SDK. Portal, trip detection, or other IMS APIs will not be available until setIdentity succeeds again.

// Before
let identity = Identity(apiKey: apiKey, externalReferenceID: userId)

identity.setIdentity { result in
    switch result {
    case .success:
        break
    case .failure(let error):
        break
    }
}
// After (use the `Identity` shape from "Identity — drop apiKey" below)
let identity = Identity(externalReferenceID: userId)

let result = await identity.setIdentity()
switch result {
case .success:
    break
case .failure(let error):
    break
}

One-time upgrade step — re-establish identity after upgrading from 1.29.x

The 1.29.x identity is not carried forward into 2.0.x. The first time an existing user launches an app built with SDK 2.0.x, SDKConfig.shared.identity will be nil even if your app considers them logged in. Without a re-setIdentity(), subsequent IMS calls have no identity to act on.

On launch, check SDKConfig.shared.identity before making any IMS API calls. If it is nil and your own session says the user is signed in, await setIdentity() first:

// On app launch, before any IMS API calls
if SDKConfig.shared.identity == nil, isUserLoggedInToIms {
    let identity = Identity(externalReferenceID: userIdForIms)
    let result = await identity.setIdentity()
    switch result {
    case .success:
        break
    case .failure:
        // User is not signed in to the SDK. Skip IMS calls this session.
        return
    }
}

Replace isUserLoggedInToIms with your own session check. Once your install base has fully moved past 1.29.x, you can remove this launch-time check; until then, keep it as an upgrade safety net.

5

hashtag
Logging out a user

clearIdentity() is new in 2.0.x and is required on every logout. Because the SDK now persists identity across launches, skipping this call leaves the previous user's identity in place — trip detection and Portal calls continue under that user until you call it.

It replaces any prior logout pattern (for example, calling setIdentity(nil)). Call it once per logout. It is async — always await it from a Task { … } or another async context. Any SDK API call made after invoking this method will fail.

await identity.clearIdentity()

hashtag
See also — new in 2.0.x (no migration required)

These additions are opt-in and require no changes to ship a working 2.0.x upgrade. Adopt them when you're ready:

PreviousAndroidNextMigration Notes

Last updated