> ## Documentation Index
> Fetch the complete documentation index at: https://developer.incode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration guide

# IncdOnboarding migration guide

## Migration to 5.45.0

### Model loading API — extended signatures and auto-unload by default

`IncdOnboardingManager.shared.loadModels` and `IncdOnboardingManager.shared.loadModelsSynchronously` now take two additional parameters:

* `modelGroup: ModelGroup` — selects which models to preload. Defaults to `.all`. Use `.idCapture` or `.faceCapture` to load only what the next flow needs.
* `autoUnload: Bool` — when `true` (default), loaded models are released automatically once onboarding finishes or is cancelled, freeing \~80–100 MB. Pass `false` to keep models resident across sessions and release them yourself via `unloadModels()`.

Existing call sites that rely on the previous defaults continue to compile without changes, but the runtime behavior is now different: models that previously stayed in memory between onboardings are released by default. If you want the prior behavior, opt out explicitly.

Old way:

```swift
IncdOnboardingManager.shared.loadModels {
  // models loaded
}

IncdOnboardingManager.shared.loadModelsSynchronously()
```

New way (equivalent, models still released after each onboarding):

```swift
IncdOnboardingManager.shared.loadModels(
  modelGroup: .all,
  autoUnload: true
) {
  // models loaded
}

IncdOnboardingManager.shared.loadModelsSynchronously(
  modelGroup: .all,
  autoUnload: true
)
```

New way (preserve previous behavior — keep models resident across sessions):

```swift
IncdOnboardingManager.shared.loadModels(autoUnload: false) {
  // ...
} 

// release explicitly when you're done with the SDK
IncdOnboardingManager.shared.unloadModels()
```

### Deepsight configuration — unified `DeepsightConfiguration` for Face Capture and Face Authentication

Selfie / Face Capture and Face Authentication now express Deepsight capture through a single `DeepsightConfiguration`, matching the Dashboard flow/workflow model:

* `DeepsightModality`:
  * `.singleFrame` — single frame, no depth data, no video liveness.
  * `.singleFrameWithDepth` — single frame with depth data, no video liveness.
  * `.singleFrameWithDepthAndVideo` — single frame with depth data and recorded video liveness.
* `DeepsightConfiguration(enabled:modality:motion:)` — `enabled` toggles Deepsight, `modality` selects what is captured, `motion` enables motion capture.

#### Selfie scan

The `addSelfieScan` overload that took `requireDepthData` / `videoLivenessRecording` is **deprecated** (not removed). Use the new overload that takes a `DeepsightConfiguration`:

Old way (deprecated):

```swift
config.addSelfieScan(
  requireDepthData: true,
  videoLivenessRecording: true
)
```

New way:

```swift
config.addSelfieScan(
  deepsight: DeepsightConfiguration(
    enabled: true,
    modality: .singleFrameWithDepthAndVideo,
    motion: true
  )
)
```

Mapping from the deprecated parameters:

| Deprecated parameters           | New `DeepsightModality`                                                |
| ------------------------------- | ---------------------------------------------------------------------- |
| `videoLivenessRecording: false` | `.singleFrameWithDepth` (depth captured, preserving previous behavior) |
| `videoLivenessRecording: true`  | `.singleFrameWithDepthAndVideo`                                        |

Notes:

* `requireDepthData` no longer affects capture — whether depth is captured is now determined by the modality.
* The new `deepsight` parameter defaults to `DeepsightConfiguration.default` (Deepsight disabled). A bare `addSelfieScan()` therefore now performs a plain single-frame capture (no depth, no video, no motion); pass an explicit `DeepsightConfiguration` to enable them.

#### Face authentication

`FaceAuthenticationConfiguration` now accepts a `DeepsightConfiguration`:

```swift
let config = FaceAuthenticationConfiguration(
  deepsight: DeepsightConfiguration(modality: .singleFrameWithDepthAndVideo, motion: true)
)
```

When a flow/workflow is fetched from the Dashboard, Deepsight is configured automatically from the backend (`ds`, `deepsightLiveness`, and `motion`); no SDK changes are required for flow/workflow-driven onboarding.

### NFC Scan Module — Redesign to Design System V2

The `NFC Scan` module has been migrated to the Incode Design System V2. The public `addNfcScan(...)` API and `NFCScanResult` are unchanged; integration code does not need to be touched. User-visible flow changes:

* After a chip-read failure, a general error screen is shown briefly before the try-again screen.
* The try-again CTA now navigates through the OCR-edit screen so users can confirm document data before retrying. Previously the CTA restarted the scan immediately.
* The passport try-again carousel advances one page per failed attempt (capped at the last page). Previously the carousel was shown only once.
* A dedicated error screen is shown when the device does not support NFC; the module then completes with `NFCScanResult.error == .notAvailable`.

Several `incdOnboarding.nfc.*` strings had their casing/copy updated, and new keys were added for V2-only screens. See `LOCALIZATION_GUIDE.md` for the full key list. No key renames or removals — overrides in your `Localizable.strings` continue to work.

### `disableJailbreakDetection` removed

The public `IncdOnboardingManager.shared.disableJailbreakDetection` property has been removed and has no replacement. If you set it anywhere, remove those calls; the code will not compile until you do.

Old way:

```swift
IncdOnboardingManager.shared.disableJailbreakDetection = true
```

New way: remove the call.

## Migration to 5.44.0

### Face Capture validation flags — defaults changed from `false` to `true`

When the dashboard configuration omits `validateLenses`, `validateFaceMask`, `validateClosedEyes`, or `validateHeadCover`, the SDK now defaults them to `true`. If you relied on these being off, set them explicitly to `false` in your dashboard configuration — otherwise the corresponding checks will start running and may reject captures that previously passed.

### `IncdTheme.logo` — now also applied to V2 screens

V2 screens now respect `IncdTheme.logo`, using it before falling back to the host app's `incdOnboardingLogo` asset and then the SDK default (V1 already worked this way). If you previously set `IncdTheme.logo` for V1 and a separate `incdOnboardingLogo` asset expecting V2 to show the asset, V2 will now show `IncdTheme.logo` on both. Leave `IncdTheme.logo` unset to keep V2 on the asset.

## Migration to 5.43.0

### `IncdFlowError` and `GeolocationError` — new cases

The reworked `Geolocation` failure UX adds new enum cases. Update any exhaustive `switch` over `IncdFlowError` or `GeolocationError`:

* `IncdFlowError.locationUnavailable` - fired via `IncdOnboardingDelegate.onError(_:)` when a non-skippable `Geolocation` module exhausts its retries on the location-unavailable screen and the user taps `Quit process`.
* `GeolocationError.locationUnavailable` - surfaced via `GeolocationResult.error` when a skippable `Geolocation` module is skipped from either failure screen.

## Migration to 5.42.0

* Removed localization keys
  * `incdOnboarding.nameInfo.lastnamePlaceholder`
  * `incdOnboarding.ccv.invalidCCV`
* Renamed localization keys:
  * `incdOnboarding.email.title` -> `incdOnboarding.userInformation.email.title`
  * `incdOnboarding.email.invalidEmail` -> `incdOnboarding.userInformation.email.wrongFormat`
  * `incdOnboarding.ccv.title` -> `incdOnboarding.userInformation.securityCode.title`
  * `incdOnboarding.nameInfo.title` -> `incdOnboarding.userInformation.fullName.title`
  * `incdOnboarding.nameInfo.subtitle` -> `incdOnboarding.userInformation.fullName.subtitle`
  * `incdOnboarding.nameInfo.namePlaceholder` -> `incdOnboarding.userInformation.fullName.placeholder`
  * `incdOnboarding.nameInfo.continue` -> `incdOnboarding.userInformation.continue`
  * `incdOnboarding.ekyc.input.label.fillYourCredentials` -> `incdOnboarding.ekyc.input.title`

## Migration to 5.41.0

### CURP Validation Module — Localization Key Changes

The CURP Validation module has been redesigned to use the Incode Design System V2. As part of this update:

* Removed localization key:
  * `incdOnboarding.curp.add.generate`
* Renamed localization keys:
  * `incdOnboarding.curp.generation.last.name.placeholder` → `incdOnboarding.curp.generation.first.last.name.placeholder`
  * `incdOnboarding.curp.generation.name.placeholder` → `incdOnboarding.curp.generation.first.name.placeholder`

If you override CURP-related strings in your `Localizable.strings`, update the keys above. Unused keys can be safely removed.

### ID Document Chooser — `idType` Behavior Change

The visibility of the ID Document Chooser screen is now controlled only by the **"Show document chooser screen"** flag on the Dashboard or `showIdTypeChooser` in `addIdScan`.

* When using startFlow / startWorkflow, the Dashboard setting is respected.
* When using **`startOnboarding` / `startOnboardingSection`**: the Dashboard flag is ignored and visibility is controlled exclusively via `showIdTypeChooser` in `addIdScan`.

Setting `idType` alone no longer hides the chooser and will be ignored.

If you use `startOnboarding` / `startOnboardingSection` and previously relied on `idType` to suppress the chooser, add an explicit `showIdTypeChooser: false`:

```swift
// Before (implicit suppression via idType — no longer works)
addIdScan(idType: .id)

// After (explicit)
addIdScan(idType: .id, showIdTypeChooser: false)
```

### V2 Theme Color Palette — Positive and Negative Token Renames

The JSON/code keys used for positive and negative semantic colors in `IncdTheme`'s V2 color palette have been renamed. If you customize the color palette via JSON or code, update the following keys:

| Old key       | New key       |
| ------------- | ------------- |
| `negative500` | `negative400` |
| `negative600` | `negative500` |
| `positive600` | `positive500` |
| `positive800` | `positive950` |

For the full updated palette reference, see [About Colors](USER_GUIDE_CUSTOMIZATION_V2.md#about-colors) in the Customization Guide v2.

## Migration to 5.40.0

* Deprecated `title` and `description` parameters from `addSignature` method.
  * Use `addSignature(descriptionMaxLines:documents:)` and customize text via these keys in your app's `Localizable.strings`:
    * `"incdOnboarding.signature.title"`
    * `"incdOnboarding.signature.description"`

## Migration to 5.39.0

* Removed `enableRotationOnRetakeScreen` parameter from `addIdScan` method. Document in the review screen is shown in vertical orientation always.
* Renamed `showRetakeScreen` into `showRetakeScreenForManualCapture` in `addIdScan` method.
* Renamed `showAutoCaptureRetakeScreen` into `showRetakeScreenForAutoCapture` in `addIdScan` method.

## Migration to 5.38.0

* Renamed `FaceAuthenticationConfiguration` struct field `showTutorial` to `showTutorials` in order to perserve consistent parameter naming with other modules.
* Deprecated `enableIdSummaryScreen` parameter from addIdProcess. Now function signature is now `addIdProcess(idCategory: IDCategory)`. Screen will not appear when using v2 UI. IdSummaryScreen will be removed in future update.

## Migration to 5.37.0

End-to-end-encryption (E2EE) no longer requires a separate "-e2ee" SDK variant and has also dropped the dependency on the `OpenSSL` framework. The separate "-e2ee" SDK variant has been deprecated.

## Migration to 5.34.0

The `brightnessThreshold` parameter has been removed in the following methods:

* IncdOnboardingFlowConfiguration - addSelfieScan
* IncdOnboardingManager - startFaceLogin
* IncdOnboardingManager - startKioskSelfieScan
  Migrate by removing the parameter from these methods.

## Migration to 5.30.0

* Removed `.hybrid` mode from `FaceAuthMode`. `.hybrid` mode can safely be replaced with `.server` when calling `startFaceLogin`.

## Migration to 5.21.0

* `FaceMatchResult.idCategory` field is now named `idCategories`

## Migration to 5.19.0

* Removed the '-m' variant for face mask check. From version 5.19.0 onward, local mask check is standard in all variants. Migrate by omitting the '-m'; e.g. update '5.18.0-d-l-m' to '5.19.0-d-l'.

## Migration to 5.18.0

Starting from version 5.18.0, IncdOnboarding utilizes Lottie vector animations in JSON format for displaying tutorials. If you have been using your own tutorials in .mp4 format, you will need to provide the corresponding animations in JSON format. For more information on setting up your own tutorials, please visit the following page [Change tutorial videos](USER_GUIDE_CUSTOMIZATION.md#change-tutorial-videos)

## Migration to 5.16.0

* Callback method for NFC Scan module has been renamed from `onPassportNFCScanCompleted(_ result: NFCScanResult)` to `onNFCScanCompleted(_ result: NFCScanResult)` in order to support NFC scan on IDs.

* `NFCScanResult`'s fields have also been renamed:
  * `passportFacePhoto` to `facePhoto`
  * `passportDG1` to `dg1`
  * `passportNFCScanError` to `error`

* `PassportNFCScanError` type is also renamed, now it is `NFCScanError`.

* `userPassportHasNoChip` error is now `userDocumentHasNoChip`.

* `HelpButtonConfiguration` is removed in favor of an improved `ButtonConfiguration`:

Old way:

```swift
  private var helpButton: HelpButtonConfiguration {

    return HelpButtonConfiguration(cornerRadius: 35,
                                   backgroundColor: Colors.background,
                                   textColor: Colors.primary,
                                   iconColor: Colors.primary,
                                   width: 140,
                                   height: 70,
                                   iconTitlePadding: 4,
                                   verticalPadding: 6,
                                   horizontalPadding: 8)
```

New way:

```swift
private var helpButton: ButtonConfiguration {
    let normal = ButtonThemedState(alpha: 1.0,
                                   backgroundColor: .incdBackground,
                                   borderColor: .incdPrimary,
                                   borderWidth: 1.0,
                                   textColor: .incdPrimary,
                                   iconImageName: "incdOnboarding.help.clipped",
                                   iconTintColor: .incdPrimary,
                                   iconPosition: .right,
                                   iconPadding: 8)
    return ButtonConfiguration(states: .init(normal: normal))
  }
```

## Migration to 5.15.0

* **Breaking Change:** The function `onEvent(_ event: Event, data: [String: Any])` has been replaced with a more comprehensive function to handle multiple events along with their associated data.
* New Function: `onEvents(_ eventsWithDetails: [EventWithDetails])`

  * `EventWithDetails` is a typealias for a tuple containing an Event and its associated data.

  * This change provides improved capability for processing multiple events and their associated data together.

***Note**: This function is intended for analytics or informative purposes only, and should not be used as an indication that all events and their effects have been executed and completed.*

Old way:

```swift
func onEvent(_ event: Event, data: [String: Any])
```

New way:

```swift
 func onEvents(_ eventsWithDetails: [EventWithDetails])
```

## Migration to 5.12.0

* `addMachineLearningConsent` parameter `type` is now one of the `RegulationType` options, instead of a `ConsentType`. `.gdpr` and `.us` options are still available.

## Migration to 5.5.0

* Renamed setting `serverSelfieFaceMaskCheck: Bool` to `faceMaskCheck: Bool`. In case of framework variant which includes local face mask check, user can specify via `IncdOnboardingManage.shared.faceMaskCheckMode` to use either server or local. Default is `.local`.

## Migration to 5.x

### Start Onboarding

Parameters `interviewId`, `configurationId`, `onboardingValidationModules`, `customFields`, `externalId` are removed.

These parameters are now provided via `IncdOnboardingSessionConfiguration`:

```swift
let sessionConfig = IncdOnboardingSessionConfiguration(configurationId: "confId",
                                                                 validationModules: [],
                                                                 customFields: ["customKey": "customData"],
                                                                 interviewId: "interviewId",
                                                                 externalId: "externalId")
```

`IncdOnboardingConfiguration` is removed, use `IncdOnboardingFlowConfiguration` instead to add modules:

```swift
let flowConfig = IncdOnboardingFlowConfiguration()
          flowConfig.addIdScan()
          ...
```

Now you can provide these to the `startOnboarding` method:

```swift
  IncdOnboardingManager.shared.startOnboarding(sessionConfig: sessionConfig, flowConfig: flowConfig, delegate: self)
```

### Setup Onboarding Session

Removed API methods:

* `createNewOnboаrdingSession`
* `setOnboardingSession`

Use the `setupOnboardingSession` instead. All the parameters of `createNewOnboаrdingSession` and `setOnboardingSession` methods are now part of `IncdOnboardingSessionConfiguration`:

```swift
let sessionConfig = IncdOnboardingSessionConfiguration(region: "ALL",
                                                       queue: .aristotle,
                                                       configurationId: "confId",
                                                       validationModules: [],
                                                       customFields: ["customKey": "customData"],
                                                       interviewId: "interviewId",
                                                       token: "token",
                                                       externalId: "externalId")

IncdOnboardingManager.shared.setupOnboardingSession(sessionConfig: sessionConfig) { sessionResult in

}
```

### Starting Onboarding Section

* `flowTag` is removed from `IncdOnboardingFlowConfiguration`, and is now a parameter inside `startOnboardingSection`:

```swift
let flowConfig = IncdOnboardingFlowConfiguration()
flowConfig.addIdScan()
IncdOnboardingManager.shared.startOnboardingSection(flowConfig: flowConfig, sectionTag: "MyTag", delegate: self)
```

## Migration to 4.7.1

* Colors passed to `IncdTheme` are not `UIColor` instead of `CGColor`. For more information please visit [IncdTheme Guide](USER_GUIDE_INCD_THEME.md).

## Migration to 4.5.0

* Added `CustomComponents` to `IncdTheme` which holds a UI customization configuration for the Camera Feedback View. For more information please visit [IncdTheme Guide](USER_GUIDE_INCD_THEME.md).
* Changed several localization keys to match style and consistency:
  ```
  "incdOnboarding.btnCancel" -> "incdOnboarding.global.button.cancel"
  "incdOnboarding.btnContinue" -> "incdOnboarding.global.button.continue"
  "incdOnboarding.btnDone" -> "incdOnboarding.global.button.done"
  "incdOnboarding.btnNext" -> "incdOnboarding.global.button.next"
  "incdOnboarding.dialog.cameraPermissionsBtnOpenSettings" -> "incdOnboarding.global.dialog.cameraPermissionsBtnOpenSettings"
  "incdOnboarding.dialog.cameraPermissionsMandatorySubtitle" -> "incdOnboarding.global.dialog.cameraPermissionsMandatorySubtitle"
  "incdOnboarding.dialog.cameraPermissionsMandatoryTitle" -> "incdOnboarding.global.dialog.cameraPermissionsMandatoryTitle"
  "incdOnboarding.dialog.ok" -> "incdOnboarding.global.dialog.ok"
  "incdOnboarding.dialog.permission.finishProcess" -> "incdOnboarding.global.dialog.permission.finishProcess"
  "incdOnboarding.err.oooops.msg" -> "incdOnboarding.global.error.generic.message"
  "incdOnboarding.err.oooops.title" -> "incdOnboarding.global.error.generic.title"
  "incdOnboarding.processing" -> "incdOnboarding.global.processing"
  "incdOnboarding.uploading" -> "incdOnboarding.global.uploading"
  "incdOnboarding.qr.scanningDone" -> "incdOnboarding.qr.scanning_done"
  "incdOnboarding.qr.scanningError" -> "incdOnboarding.qr.scanning_error"
  "incdOnboarding.govValidation.inProgress" -> "incdOnboarding.govValidation.in_progress"
  "incdOnboarding.govValidation.startedSuccessfully" -> "incdOnboarding.govValidation.startedSuccessfully"
  "incdOnboarding.govValidation.success" -> "incdOnboarding.govValidation.success"
  "incdOnboarding.govValidation.failure" -> "incdOnboarding.govValidation.failure"
  "incdOnboarding.govValidation.error.connection" -> "incdOnboarding.govValidation.connection_error"
  "incdOnboarding.govValidation.error.ineInfrastructure" -> "incdOnboarding.govValidation.ine_infrastructure_error"
  "incdOnboarding.govValidation.error.moduleNotSupported" -> "incdOnboarding.govValidation.module_not_supported_error"
  "incdOnboarding.govValidation.error.missingDocumentIdentifier" -> "incdOnboarding.govValidation.missing_document_identifier_error"
  "incdOnboarding.govValidation.error.missingSelfie" -> "incdOnboarding.govValidation.missing_selfie_error"
  "incdOnboarding.govValidation.error.userNotFound" -> "incdOnboarding.govValidation.user_not_found_error"
  "incdOnboarding.govValidation.error.userNotInDatabase" -> "incdOnboarding.govValidation.user_not_in_database"
  "incdOnboarding.govValidation.error.insufficientLookupData" -> "incdOnboarding.govValidation.insufficient_lookup_data"
  ```
  For the full instructions on the localization please visit [Localization Guide](LOCALIZATION_GUIDE.md).

## Migration to 4.1.0

* Updated Document Scan flow that supports the option to upload a PDF or image from the device. Potentially breaking change: `.document` is now `.addressStatement`.
* Tutorials for Document Scan are now disabled by default, and the document provider screen is enabled by default. Many of the texts have been updated so please take a look at the full list [here](USER_GUIDE_CUSTOMIZATION.md#change-the-texts).

## Migration to 4.0.0

* Individual functions are removed:
  * Please use sections API instead and add a module via `IncdOnboardingFlowConfiguration.add<module>()` method.
* Removed any deprecated API which was using parameter `vc: UIViewController`. Please switch to the same functioins without the `vc` parameter.
* If you are using ID Scan module, it is required to switch to a new result structure `IdScanResult`. Check [User Guide](USER_GUIDE.md) for more info.

## Migration from 1.10.x to 1.11.0

For version 1.11.0 ID and Selfie capture are customized via IncdTheme.
If you are using UI customization please visit [IncdTheme Guide](USER_GUIDE_INCD_THEME.md).

* New option -
  Allow users to cancel ID or Selfie capture by showing close (X) button:

```
IncdOnboardingManager.shared.allowUserToCancel
```

Default is `false`.

## Migration from 1.9.x to 1.10.x

`vc: UIViewController` parameter is now deprecated in most of calls.
Please assign the `vc:` parameter to `IncdOnboardingManager.shared.presentingViewController` and remove the `vc:` parameter from the API.

Example:

1.9.x

```
IncdOnboardingManager.shared.startOnboarding(vc: self)
```

1.10.x

```
IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startOnboarding()
```

## Project Migration Guide from 1.9.42 to 1.9.46

Framework is now being delivered as a static IncdOnboarding.xcframework, so that only `opencv2` and `OpenTok` frameworks need to be added to the project alongside main `IncdOnboarding.xcframework`

### Make sure `git lfs` is installed

Some framework files exceed 100MBs, so Git Large File Storage is needed to be setup. Please find the instrcutions here:
<https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage>

### Framework files update

* Remove IncdNetwork, IncdFaceDetection, IncdRecogKit, IncdUIKit frameworks and IncdUIKit.bundle (also remove any imports in code from these modules if you have them)
* Add opencv2.framework
* Replace current OpenTok.framework and IncdOnboarding.xcframework
* Replace current IncdOnboarding.bundle

### Change Project Settings

1. Add following to the `Other Linker Flags`:
   `-l “stdc++” -l “iconv” - framework “VideoToolbox”`
2. IncdOnboarding.xcframework, opencv2.framework and OpenTok.framework should be set to `Do not Embed’`

### Code updates

Error handling has been improved and simplifed, in particular:

* `IncdOnboardingDelegate` and its `onError` callback now return `IncdFlowError` instead of `IncdOnboardingError`. You'll be notified here about all the possible errors that abort the flow.
* `IncdOnboardingDeletegate` and some of its callback methods once the steps are completed no longer have `ResultCode` field used to determine if the step finished successfully or not. You can always check if the `error` field in the result is `nil` to identify successful step completion, or see if some error occured.

## 1.9.14 -> 1.9.25

### Migration steps:

Moving ID auto-capture timeouot configuration to server.

1. Remove `idAutoCaptureTimeout` parameter if present anywhere. Timeout can be set on server through REST API.

## 1.8.x -> 1.9.14

### Migration steps:

1. Remove OpenTok from Cocoapods. If that was your only Pod then you can deintegrate Cocoapods altogether.
2. Remove the “models” folder from the project and from the file system.
3. Remove the “models” from the target’s “Build Phases” -> “Copy Bundle Resources” section.

## 1.6.x -> 1.8.x

### Migration steps:

1. Document type `.addressproof` has been renamed to `.document` for scanning documents using `addDocumentScan(: DocumentType)`.
2. Usage of `IncdRegion` is deprecated. `IncdOnboardingConfiguration` init now takes a `regionCode: String` as a parameter. Before it was `IncdRegion`.