# iOS

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

Sections are ordered for a typical integration.

{% stepper %}
{% step %}

#### Platform and Build

* Minimum deployment target `iOS 15`.
* Build with `Xcode 26` or newer. The 2.0.x artifacts are produced with that toolchain.
  {% endstep %}

{% step %}

#### Initialization

Remove these arguments from `initialize(...)`:

* `configRegion`
* `configEnvironment`

Also remove any code that depends on `region` or `environment` from the SDK.
{% endstep %}

{% step %}

#### Identity - drop apiKey

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

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

```swift
// After
let identity = Identity(externalReferenceID: userId)
```

{% endstep %}

{% step %}

#### Logging in a user

{% hint style="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.](#toc_3)
{% endhint %}

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.

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

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

```swift
// 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:

```swift
// 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.
{% endstep %}

{% step %}

#### 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.

```swift
await identity.clearIdentity()
```

{% endstep %}
{% endstepper %}

## 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:

* Crash Detection events — listen for crash events and submit user feedback via `TripDetectionManager.getCrashClient()`. See [Crash Detection events](https://sdk.ims.tech/~/changes/197/crash-detection-events).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdk.ims.tech/migration-guides/migrating-from-1.29.x-to-2.0.x/ios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.