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