Migration guide

Face Capture and Face Authentication: New videoRecordingFailed Case and Background-Recovery Change

SelfieScanError and FaceAuthenticationError each gain a new case:

case videoRecordingFailed  // new

The case is reported when the Deepsight video could not be recorded or finalized — for example when the hardware video encoder was invalidated while the app was in the background. It is non-fatal: the face capture itself completes normally, and the failure is surfaced only via the existing videoRecordingError field on SelfieScanResult / FaceAuthenticationResult — the error field remains reserved for terminal failures, so existing error handling is unaffected. If you switch exhaustively over SelfieScanError or FaceAuthenticationError, add a handler for this case.

Behavior change: backgrounding the app during Face Capture or Face Authentication used to lose the Deepsight video silently, because the invalidated encoder only failed at finalization. The SDK now discards the pre-background footage and records a fresh clip once the app returns to the foreground, so the uploaded video covers the capture from the resume point onward. No call-site changes are required for this.

ID Capture: New IDFrameAnalysisError.preparingCamera Case

IDFrameAnalysisError gains a new case:

case preparingCamera  // new

preparingCamera is reported through IDCaptureFeedback.error while the ID camera is getting ready, before the preview is shown. It is not an error: capture continues normally once the camera is ready, and the SDK's own screens show the existing "Adjusting camera" copy for it, just like settingUpStreaming. If you switch exhaustively over IDFrameAnalysisError, add a handler for this case.

testMode Now Allowed on Real Devices

initIncdOnboarding(...) with testMode: true used to fail on a real device with IncdInitError.testModeEnabled. It now succeeds, so you can develop against a real device with test mode on. The SDK prints a console warning when test mode is enabled to remind you to set it back to false before distribution.

IncdInitError.testModeEnabled is kept so existing switch statements keep compiling, but it is no longer reported. Remove any handling that relied on initialization failing for this reason.

AES: showCertificateOnSuccess Removed from addAes

The AES module now shows a V2-style success screen instead of listing the signed documents. showCertificateOnSuccess had no other effect, so it was removed from addAes(...). Downloading the signed document is unchanged and still follows AESConfiguration.downloadDocument. When enabled, the success screen offers a "Download document" action.

Old way:

flowConfig.addAes(configuration: aesConfiguration, showCertificateOnSuccess: true)

New way:

flowConfig.addAes(configuration: aesConfiguration)

The code will not compile until the argument is removed. AESConfiguration and AESResult are unchanged.

Electronic Signature (AES/QES): V2 Screens and Localization Key Changes

Both signature modules now run on the Incode Design System V2. The addQes(...) API and both result types are unchanged. User-visible changes include:

• QES now honors QESConfiguration.uploadDocument. When enabled, the user picks and uploads a PDF before the signing screen, just like AES. Previously, the flag was ignored, so a session with no documents attached ended with QESResult.error == .noDocuments.
• Both signing screens show the close button whenever IncdOnboardingManager.shared.allowUserToCancel allows it. Previously, it was suppressed unconditionally.

Localization key changes include:

• Removed (overrides of these keys no longer have any effect):
  • incdOnboarding.qes.terms1.title
  • incdOnboarding.qes.terms2.title
• Added:
  • incdOnboarding.qes.consent.qualifiedCertificate, .legalEffect, .qscd, .termsPrivacy, and .reviewedDocuments: The five consent checkboxes on the QES signing screen, replacing the two removed keys above.
  • incdOnboarding.aes.document.namePosition and incdOnboarding.qes.document.namePosition: The document card name used when more than one document is signed.
• Copy updated without renames, so existing overrides keep working: incdOnboarding.aes.terms1.title, .terms2.title, .terms3.title, incdOnboarding.aes.acceptSign.subtitle, incdOnboarding.aes.document.name, and incdOnboarding.qes.document.name. The last two now hold the single-document name and no longer take a number.

See Localize Display Text for the full key list.

Face Capture and Face Authentication: New videoRecordingError Field and insufficientStorageForVideoRecording Case

SelfieScanResult and FaceAuthenticationResult gain a new optional field:

public var videoRecordingError: SelfieScanError?          // on SelfieScanResult
public var videoRecordingError: FaceAuthenticationError?  // on FaceAuthenticationResult

SelfieScanError and FaceAuthenticationError each gain a new case:

case insufficientStorageForVideoRecording  // new

The case is reported when Deepsight video recording is skipped because the device has less than 15 MB of free storage. It is non-fatal: the face capture itself completes normally, and the skip is surfaced only via videoRecordingError. The error field remains reserved for terminal failures, so existing error handling is unaffected. If you switch exhaustively over SelfieScanError or FaceAuthenticationError, add a handler for this case.

Signature: New SignatureError.retryLimitReached Case

SignatureError gains a new case:

public enum SignatureError {
  case error(_ error: IncdError)
  case declinedToSignDocument
  case retryLimitReached          // new
}

retryLimitReached is returned in SignatureFormResult.error when the user exceeds the maximum number of allowed signing attempts. If you switch exhaustively over SignatureError, add a handler for this case.

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:

IncdOnboardingManager.shared.loadModels {
  // models loaded
}

IncdOnboardingManager.shared.loadModelsSynchronously()

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

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

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

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

New way:

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

Mapping from the deprecated parameters:

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:

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 SDK Customization 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:

IncdOnboardingManager.shared.disableJailbreakDetection = true

New way: remove the call.

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.

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.

• 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

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:

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

For the full updated palette reference, see About Colors in the Customization Guide v2.

• 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"

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

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