---
title: "Web SDK 2.x Migration Guide"
url: "https://developer.incode.com/release-notes/web-sdk-2x-migration-guide/"
section: "release-notes"
group: "Releases Web SDK / Web SDK 2.0 Release Notes"
version: "v1.1"
status: "live"
---
# Web SDK 2.x Migration Guide
<Component slug="web-2-x-implementation-warning" />

## Migrate to Web SDK 2.5.0

This section covers changes from 2.4.x to 2.5.0. The replacement behavior below targets **2.5.0 or later**. Keep core and web on matching versions. No API is removed in 2.5.0; the items below change behavior, deprecate options, or can affect custom styles and tests. Review the ones that apply to your integration.

### Handoff links and session options

**Before:** a desktop-to-mobile handoff link restarted the session through the same request that creates a session, and `createSession` accepted `interviewId` and `externalId` to resume or tag a session.

**In 2.5.0:** `createSession`, `bootstrapSession`, and the self-loading `<incode-flow>` and `<incode-workflow>` continue the existing session when `uuid` is set. The same call is exported as `continueSession` from `@incodetech/core/session`. The server limits how many times a link can continue a session within 48 hours of the session start, so every load of the link, including a reload, uses one. The SDK does not retry a continue and does not refresh an expired token.

A refused continue throws an `IncodeApiError` whose `status` is one of `SESSION_CONTINUE_ERROR_CODES` from `@incodetech/core/session`: `4026` (unknown or expired link), `4081` (QR validation failed), `4086` (48-hour window passed), `4087` (continuation limit reached), or `4088` (session no longer active). For these codes, the initialization error screen does not offer "Try again", because reloading the same link fails the same way. Show your own guidance or start a new session.

The `interviewId` and `externalId` options of `createSession` (and of the self-loading `<incode-flow>` and `<incode-workflow>` config) are deprecated. They still work in 2.5.0, but session restarts through them are being retired. If you pass `interviewId` to resume a session after the user opens a handoff link, pass the link's `uuid` instead (and `urlUuid` when the link has one). When `uuid` is set, the SDK sends only `uuid` and `urlUuid`, so other options such as `configurationId`, `language`, and `customFields` are not sent on a continue.

```ts
// Before
await createSession(apiKey, { configurationId, interviewId });

// 2.5.0
await createSession(apiKey, { configurationId, uuid, urlUuid });
```

See [Session API](/sdk-reference/web-sdk-2-session-api/).

### Redirect to Mobile URL validation

**Before:** an invalid custom `redirectToMobileUrl` (or module `url`) threw while the QR code URL was built, so the module never reached its error state and `onError` did not fire.

**In 2.5.0:** the module accepts an absolute `http://` or `https://` URL, or a path that starts with `/`, which resolves against your app's origin. Any other value, such as `www.example.com`, moves the module to its error state before any request, and `onError` receives `INVALID_REDIRECT_URL` as its third argument. Add the scheme or a leading `/` to the value. See [Redirect to Mobile](/sdk-reference/web-sdk-2-module-redirect-to-mobile/).

### Offline screen

**Before:** most modules found out that the device was offline only when a request failed, and each handled it differently.

**In 2.5.0:** when the browser goes offline, the outermost SDK element shows one "No internet connection" screen in every module, standalone, in `<incode-flow>`, or in `<incode-workflow>`. The current step unmounts while the device is offline, and the SDK calls none of your `onError`, `onFinish`, or `onContinue` callbacks. The screen closes by itself shortly after the browser reports it is online again, and the step restarts from its first screen. Attempts that the step already used stay used.

The screen also has a **Close** button. When the user selects it, the SDK stops the module (or the whole Flow) and calls `onError` with `NO_INTERNET_CONNECTION` as the third argument (`moduleErrorCode`). A standalone module that you gave your own `manager` cannot restart, so it reports the same code when the connection returns. Handle this code in `onError`.

- **Custom UIs:** use `onConnectivityChange(listener)`, `isConnectivityLost()`, and `resumeConnectivity()` from `@incodetech/core/session` to render your own offline state.
- **Custom connection error screens:** `ConnectionError` from `@incodetech/web/extensibility` gains an optional `onClose`. Its `onRefresh` is optional and deprecated, because the screen never reloads the page: a reload restarts a flow at its first step and uses another session continue.
- **Geolocation:** the `noNetwork` member of `GeolocationState` is deprecated and never emitted. A connection failure while submitting coordinates moves the module to `error` without using an attempt. Remove any `noNetwork` handler that you rely on for retries.

### Blocked camera reported to onError

**Before:** when the browser blocked the camera, ID Capture, Selfie, Authentication, Video Selfie, Document Capture, and Fiscal QR showed the steps to allow it, and did not tell your app.

**In 2.5.0:** those modules still show the steps, and they also call `onError` once with `CAMERA_PERMISSION_DENIED` as the third argument (`moduleErrorCode`). `<incode-flow>` and `<incode-workflow>` report the same code and keep the camera instructions on screen instead of a generic error page. `<incode-flow>` also forwards the second and third `onError` arguments for every module. If your `onError` handler closes the host page or replaces the element for any call, filter this code first:

```ts
onError: (message, errorCode, moduleErrorCode) => {
  if (
    moduleErrorCode === 'CAMERA_PERMISSION_DENIED' ||
    moduleErrorCode === 'NO_INTERNET_CONNECTION'
  ) {
    return; // The SDK is already showing instructions to the user.
  }
  // Your existing error handling.
},
```

### Video Selfie validation attempts

**Before:** when speech validation failed on every allowed attempt, Video Selfie called `onFinish`, so your app saw a success.

**In 2.5.0:** the module calls `onError` with `VIDEO_SELFIE_VALIDATION_ATTEMPTS_EXHAUSTED` as the third argument (`moduleErrorCode`) instead. `<incode-flow>` and `<incode-workflow>` stop after exhausted Video Selfie speech, selfie, or ID validation, and the error screen offers "Try again", which reloads the page. Connection and technical failures stay recoverable and do not use an attempt. If your `onFinish` handler assumes the user passed, handle this code in `onError`. See [Video Selfie](/sdk-reference/web-sdk-2-module-video-selfie/).

### Studio themes and logos

**Before:** `<incode-flow>` and `<incode-workflow>` themed themselves from the dashboard theme only.

**In 2.5.0:** when your tenant has published a theme in [Incode Studio](/design-and-ux/incode-studio/), both elements use it on upgrade, with no code change: the color palette, the button corner radius, the light and dark logos, and the "Verified by Incode" footer. Tenants without a published Studio theme keep the Dashboard theme. Your own `logoSrc`, `logoDarkSrc`, and `hideFooterBranding` values still win, and CSS that you import wins over fetched colors. `<incode-workflow>` now also reads the theme subtitle; set `subtitle` with `setUiConfig` to keep your own.

- **Logo sizing:** a custom header logo is sized by its shape. A wide logo (1.5:1 or wider) fits a 180×36px box. A squarish logo is 44px tall on a phone and 64px tall from 768px wide. SVG logos fill their box; PNG and JPG logos shrink to fit but are never enlarged. Export raster logos at least 360×72px (wide) or 128×128px (squarish), or use an SVG.
- **`uiConfig.logoHeight`:** deprecated. It has no effect.
- **Default logo:** the Incode logo uses the brand color instead of a fixed blue.
- **New helper:** `applyStudioConfig` from `@incodetech/web` applies a downloaded Studio export in one call.

See [Theming](/sdk-reference/web-sdk-2-theming/).

### Styles and tests

The SDK adopts the Prizma design system in 2.5.0. Nothing changes for integrations that use the SDK defaults or its documented tokens. If you style SDK screens with your own CSS, or select elements in tests, check the following:

- **Button corner radius:** the `buttonBorderRadius` of your dashboard theme, the `--button-primary-border-radius` and `--button-secondary-border-radius` tokens, and the corner radius of an Incode Studio theme now apply to SDK buttons. Before, buttons always used the default 16px radius. If your theme sets a radius, your buttons change corners when you update. `buttonBorderRadius` needs a CSS length with a unit, such as `"30px"` or `"1.5rem"`; a bare number is read as pixels, and an invalid value is ignored. Your own `--incode-button-primary-radius` and `--incode-button-secondary-radius` CSS still wins.
- **Removed tokens:** `--primitive-typography-paragraph-spacing-*` and `--typography-*-paragraph-spacing` are removed. No SDK style read them, so overriding them had no effect.
- **Font tokens:** `--primitive-typography-family-dm-sans` and `--primitive-typography-family-rethink-sans` now end with `system-ui, sans-serif`. If you override them, add your own fallback.
- **CURP results:** the classes `IncodeCurpSuccess`, `IncodeCurpFailure`, `IncodeCurpSuccessTitle`, `IncodeCurpFailureTitle`, and `IncodeCurpFailureHint` are no longer rendered. Use the `IncodeVerificationResult*` classes. The retry button's test id is `verification-retry` (was `curp-retry`).
- **ID icons:** `IncodeIdExpiredIcon`, `IncodeIdNoAttemptsIcon`, and `IncodeIdProcessingResultIcon` are no longer rendered.
- **Video Selfie loaders:** the processing indicators render `.prizma-loading-spinner` (48px) instead of `IncodeLoadingIcon`, `IncodeVsIdFeedbackSpinnerPrimary`, and `IncodeVsIdFeedbackSpinnerSecondary`.
- **Headings:** screen headings render inside a title wrapper. Their `Incode*` classes stay on the heading, but selectors that depend on its parent or position, such as `.parent > h2`, may no longer match.
- **Status icons** on result and error screens are 40px.

### Localization

**Before:** `createI18n()` returned an i18next instance.

**In 2.5.0:** `@incodetech/web` translates with a small built-in translator. `createI18n()` no longer returns an i18next instance, so code that calls i18next methods on it, such as `addResourceBundle`, must use the SDK's `translations` or `loadPath` options instead. The translator supports `{{name}}` interpolation and the plural suffixes of the active language (`_zero`, `_one`, `_two`, `_few`, `_many`, and `_other`). Strings that use other i18next syntax (`$t(...)` nesting, `{{value, format}}` formatters, `context`, ordinal plurals, or `returnObjects`) render without it. See [Localization](/sdk-reference/web-sdk-2-i18n/).

### Face Match results

**Before:** Face Match always called the score service, so an organization that does not allow score retrieval stopped on "Process was not completed", and a failed face-image request failed the module.

**In 2.5.0:** Face Match reads the match result from the face processing response when it is present, and requests the score only when it is absent. When a selfie capture in the same session already received the result, Face Match shows it without another call. `FaceMatchConfig` gains an optional `matched` field for integrations that pass the result in after a full page load.

- **Liveness:** `FaceMatchResult.liveness` is `null` when Face Match does not request the score, and when a score has no liveness status. The result screen then shows no liveness snackbar, where it used to show "Liveness failed" for a score with no status. Handle `null` in custom UIs.
- **Images:** a failed face-image request gives `null` images and keeps the match result. A missing image shows as a plain gray circle.
- **Animation:** with `disableFaceMatchAnimation: true`, Face Match no longer fetches face images.

See [Face Match](/sdk-reference/web-sdk-2-module-face-match/).






### eKYC form steps

**Before:** the eKYC form showed every section on one screen.

**In 2.5.0:** the form splits into one step per section, with a progress bar and a Back button. For custom UIs, the manager's `form` state adds `steps`, `currentStepIndex`, and `isStepValid`, and the manager adds `next()` and `back()`. `submit()` still validates and submits the whole form from any step, so existing headless integrations keep working. When a field fails validation, the form moves to the first step with an error. See [eKYC](/sdk-reference/web-sdk-2-module-ekyc/).

### Deprecated APIs

These APIs remain callable in 2.5.0 so existing code keeps compiling. Full removal is planned for 3.0.0. Prepare by removing the calls.

| Previous usage | Replacement or required action |
| --- | --- |
| `interviewId` and `externalId` options of `createSession`, `<incode-flow>`, and `<incode-workflow>` | Continue a handoff session with `uuid`. See [Handoff links and session options](#handoff-links-and-session-options). |
| `uiConfig.logoHeight` | Remove the option. It has no effect. |
| `onRefresh` on `ConnectionError` from `@incodetech/web/extensibility` | Use `onClose`. |
| `noNetwork` in `GeolocationState` | Remove the handler. The state is never emitted. |
| `isVirtualCamera()` on `WasmUtilProvider` | Remove the call. It always returns `false`. Removal is planned for 3.0.0. |
| `prc()`, `setZc()`, and `setBackgroundMode()` on `WasmUtilProvider` | Remove the calls. They do nothing. No replacement is needed. |

## Migrate to Web SDK 2.4.0

<Accordion title="Migrate to Web SDK 2.4.0">

This section covers changes from 2.3.x to 2.4.0. The replacement behavior below targets **2.4.0 or later**. Keep core and web on matching versions. Removed APIs have no compatibility period in 2.4.0; complete the applicable migration before upgrading.

Review the sections that apply to your configuration, custom UI, deployment, or styles. Applications using SDK components still need to check removed configuration options.

### Manual upload removal

**Before:** `manualUploadIdCapture` and `manualUploadSelfieCapture` let the user upload an ID or selfie image from a file. Custom UIs handled the `manualUpload` state and called the manual-upload methods.

**In 2.4.0:** both options are removed, together with their states, methods, and fields. Use camera capture or [Digital ID](/sdk-reference/web-sdk-2-module-id-capture/) for supported documents.

| Previous usage | Required action |
| --- | --- |
| `manualUploadIdCapture` in ID Capture configuration | Remove the option. |
| ID Capture `manualUpload` state, `manualUploadChangeTab(tab)`, `manualUploadSelectFile(side, file)`, `manualUploadContinue()`, and `manualUploadReset()` | Remove the state handler and the calls. |
| `manualUploadSelfieCapture` in Selfie configuration | Remove the option. |
| Selfie `manualUpload` state, `goToManualUpload()`, `manualUploadSelectFile(file)`, and `manualUploadContinue()` | Remove the state handler and the calls. |
| `showManualUploadLink` in Selfie `tutorial` state fixtures | Remove the field from typed fixtures. |

### WASM integrity checks

**Before:** the SDK ran the WASM binaries, glue files, and models that it downloaded.

**In 2.4.0:** the SDK checks each WASM file against the official files for its release before it runs the file. The check applies wherever the files are hosted: the Incode CDN or a self-hosted copy. If a file does not match, the SDK does not run it and WASM initialization fails.

- **Strict Content-Security-Policy:** the SDK loads the verified glue from a `blob:` URL. Add `blob:` to your `script-src` directive.
- **Self-hosted WASM:** serve the unmodified distribution that matches your SDK version. Files from another release no longer load, so refresh the full distribution each time you upgrade. See [Hosting WASM Files](/sdk-reference/web-sdk-2-wasm/#hosting-wasm-files).
- **Secure pages:** the check needs `crypto.subtle`, which browsers expose only on pages served over HTTPS or from `localhost`.

For each integrity error code and its fix, see [Troubleshooting](/sdk-reference/web-sdk-2-troubleshooting/#wasm-issues).

### Capture-only ID responses

**Before:** `CaptureOnlyResponse.frontImage` was always present, and a back-only capture (`onlyBack: true`) did not call `onCapture`. With an `onCapture` callback, `createIdCaptureManager` and `<incode-id>` could run the regular upload flow instead of the capture-only flow.

**In 2.4.0:** `CaptureOnlyResponse` is a union. `frontImage` is `undefined` for a back-only capture, which now calls `onCapture` with the back image. TypeScript code that reads `response.frontImage.blob` no longer compiles. Check `frontImage` first:

```typescript
import type { CaptureOnlyResponse } from '@incodetech/core/id';

declare function uploadToMyBackend(front?: Blob, back?: Blob): Promise<void>;

async function handleCapture(response: CaptureOnlyResponse) {
  await uploadToMyBackend(response.frontImage?.blob, response.backImage?.blob);
}
```

An ID configuration with `onCapture` now always runs the capture-only flow. Nothing is uploaded, and only the capture-only fields apply: `showTutorial`, `captureAttempts`, `autoCaptureTimeout`, `deviceIdleTimeout`, `enableId`, `enablePassport`, `onlyFront`, `onlyBack`, and `showDocumentChooserScreen`. Runtime behavior for front and front-and-back captures does not change. See [ID Capture](/sdk-reference/web-sdk-2-module-id-capture/).

### Flow completion redirects

**Before:** the flow completion screen navigated to any `redirectionUrl`.

**In 2.4.0:** the SDK navigates only to an absolute `https` URL. For any other value, the completion screen shows, and the console logs a warning. For local development, an `http://localhost` URL is allowed while the page itself runs on `localhost`. The [Digital ID bank redirect](/sdk-reference/digital-id-redirect) uses the same rule.

Change any `http` redirect URL in your flow configuration to `https`.

### Session expiry

**Before:** when the current session expired, the next request failed inside the module, and each module handled that failure separately.

**In 2.4.0:** when a request for the current session returns HTTP 401, the SDK ends every mounted module, Flow, and Workflow, and releases the camera. It then calls `onError` once, with `SESSION_EXPIRED` as the third argument and the error object as the fourth:

```typescript
onError('Session expired', 401, 'SESSION_EXPIRED', error);
```

- **Components:** handle `SESSION_EXPIRED` in `onError`, for example by starting a new session and mounting a new element.
- **Host-supplied managers:** the SDK stops a manager that you pass through the `manager` prop. A stopped manager cannot be reused, so create a new one for the replacement session.
- **Headless integrations:** subscribe with `onSessionExpired()`. Each subscription is called once.

```typescript
import { onSessionExpired } from '@incodetech/core/session';

const unsubscribe = onSessionExpired((error) => {
  // error.code is 'SESSION_EXPIRED' and error.statusCode is 401.
  // Stop your managers, start a new session, and create new managers.
});

// Call unsubscribe() when the owner of the subscription unmounts.
```

A connection failure with no HTTP status does not expire the session. Requests that do not carry the session token do not expire it either.

### Workflow completion copy

**Before:** `onFinish` for `<incode-workflow>` returned `endScreenTitle` and `endScreenText` as `null`, even when Dashboard had custom completion copy.

**In 2.4.0:** self-loading Workflows fill both fields from Dashboard. In token mode, the SDK does not see your session response. Forward both values from the response to the component:

```ts
<incode-workflow
  config={{ token: sessionToken, endScreenTitle, endScreenText }}
  onFinish={handleFinish}
/>
```

See [Workflow](/sdk-reference/web-sdk-2-module-workflow/#self-loading-vs-token-mode).

### Field Comparison validation

**Before:** Field Comparison enabled Continue only after the user completed the first and last name.

**In 2.4.0:** Continue starts enabled. Submitting a blank first or last name shows a required-field error for each missing value and disables Continue until the user corrects them. In a custom UI, render the manager's validation feedback and do not add a separate completeness gate. See [Field Comparison](/sdk-reference/web-sdk-2-module-field-comparison/).

</Accordion>

## Migrate to Web SDK 2.3.0

<Accordion title="Migrate to Web SDK 2.3.0">

This section covers changes from 2.2.0 to 2.3.0. The replacement behavior below targets **2.3.0 or later**. Keep core and web on matching versions. Removed APIs have no compatibility period in 2.3.0; complete the applicable migration before upgrading. No later removal or restoration date is implied.

Review the sections that apply to your configuration, custom UI, deployment, or event consumers. Applications using SDK components still need to check removed imports and setup options.

### Feature-management readiness

**Before:** `await setup()` waited for feature-management initialization. A host could read a gate immediately afterward.

**In 2.3.0:** initialization runs in the background by default. Early reads can return defaults while initialization is pending. To preserve blocking behavior, use core setup with `awaitInitialization: true`:

```typescript
import { setup } from '@incodetech/core';
import { getFeatureGate } from '@incodetech/core/feature-management';

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  featureManagement: { awaitInitialization: true },
});
const gate = getFeatureGate('YOUR_GATE_NAME');
```

Alternatively, keep background initialization and await `getIsFeatureManagementInitialized()` from `@incodetech/core/feature-management` before a dependent read. It resolves to `false` if initialization is unavailable or fails; handle your configured fallback. SDK Flow, Workflow, and module-owned reads already wait where required.

If switching a component integration to core setup, retain its presentation setup as described in [Which setup do I call?](/sdk-reference/web-sdk-2-reference/#when-you-deliberately-use-cores-setup-with-web-components).

### Government Validation

**Before:** custom integrations could configure `backgroundExecution` and `maxOtpAttempts`, render OTP/result screens, and call OTP or retry methods.

**In 2.3.0:** remove those two configuration properties. The public states are `idle`, `loading`, and `finished`; `load()` starts the request. The manager still provides `subscribe()`, `getState()`, and `stop()`.

Remove calls to `submitOtp()`, `setOtpCode()`, `validateOtp()`, `resendOtp()`, and `retry()`. Remove handlers for `awaitingOtp`, `verifyingOtp`, `displaySuccess`, and `error`, and stop reading `otpResponse`.

```typescript
import { createGovernmentValidationManager } from '@incodetech/core/government-validation';

const manager = createGovernmentValidationManager({
  config: { facialValidation: true, dataValidation: true },
});
const unsubscribe = manager.subscribe((state) => {
  if (state.status === 'loading') {
    // Show progress.
  } else if (state.status === 'finished') {
    // Advance the UI; completion does not establish verification approval.
  }
});
manager.load();

function disposeGovernmentValidation() {
  unsubscribe();
  manager.stop();
}
```

The module advances after the request regardless of the validation outcome. Use your supported server-side verification result to make business decisions. See [Government Validation / INE Validation](/sdk-reference/web-sdk-2-module-gov-validation-1/).

### Form validation

**Before:** Custom Fields and Watchlist for Business gated Continue on completed input. Custom UIs could follow that completeness check.

**In 2.3.0:** Continue starts enabled, and submission validates required fields. Render the manager's validation feedback and let the manager validate submission. The optimistic `canSubmit` value means no errors are currently displayed; it does not establish that all required input is present. Watchlist for Business still exposes `isValid` separately; use `canSubmit` to enable Continue. Avoid adding a separate validation gate that hides the manager's feedback.

See [Custom Fields](/sdk-reference/web-sdk-2-module-custom-fields/) and [Watchlist for Business](/sdk-reference/web-sdk-2-module-watchlist-for-business/).

### Headless states and test fixtures

**Before:** exhaustive switches and typed fixtures could rely on the 2.2.0 unions and required fields.

**In 2.3.0:** add the following cases and fields. Read them only after narrowing `state.status`; use the linked reference for each complete payload.

| Module | Update |
| --- | --- |
| Selfie | Handle `manualUpload`, with `phase`, `uploaded`, `canContinue`, `errorKey`, and `attemptsRemaining`. Add required `showManualUploadLink` to tutorial fixtures. Offer `goToManualUpload()` only from the tutorial when the flag is true. Submit files with `manualUploadSelectFile(file)` and call `manualUploadContinue()` when `canContinue` is true. |
| ID Capture | Update `loading`, `tutorial`, and `permissions` fixtures with their new presentation fields. Render from `phase`, `selectedDocumentType`, `currentMode`, and `tutorialEnabled` where present; read `usingBackCamera` for mirroring. See [ID Capture state properties](/sdk-reference/web-sdk-2-module-id-capture/). |
| ID digital methods | Handle the `digitalIdRedirect` and `deviceWallet` states when those methods are enabled. Show redirect success until the user calls `digitalIdRedirectContinue()`. Follow the method-specific actions in [ID Capture](/sdk-reference/web-sdk-2-module-id-capture/). |
| Fiscal QR | Handle `permissionDenied` with browser-permission instructions and a page reload after correction. It is not a retryable scan-error state. |
| Dynamic Forms | Handle `submitFailed` with failure feedback and call `retry()` on user request. |

For example, a 2.2.0 Selfie tutorial fixture could contain only `status: 'tutorial'`. Its 2.3.0 replacement includes the upload-link flag:

```typescript
import type { SelfieState } from '@incodetech/core/selfie';

const tutorial: Extract<SelfieState, { status: 'tutorial' }> = {
  status: 'tutorial',
  showManualUploadLink: false,
};
```

Authentication and Selfie capture-only share face state types, but do not support the Selfie manual-upload journey. Do not enable upload controls for them. See [Selfie](/sdk-reference/web-sdk-2-module-selfie-1/), [Fiscal QR](/sdk-reference/web-sdk-2-individual-modules/#compliance-consent), and [Dynamic Forms](/sdk-reference/web-sdk-2-module-dynamic-forms/).

### Accepted document types

**Before:** `UploadIdResponse.acceptedDocuments` was declared as objects with `type` and `name`. Code could read `entry.name`.

**In 2.3.0:** each entry is a string. Read the entry directly, tolerate unknown values, and hide the list when it is absent or empty. The capture state exposes `acceptedDocuments` and `countryCode` for error presentation:

```typescript
import type { IdCaptureState } from '@incodetech/core/id';

function acceptedDocumentNames(state: IdCaptureState): string[] {
  if (state.status !== 'capture') return [];
  return state.acceptedDocuments ?? [];
}
```

See [ID Capture](/sdk-reference/web-sdk-2-module-id-capture/) for the full error-state presentation.

### Self-hosted assets and fonts

**Before:** custom deployments could copy only `base.css`, inject its text without resolving asset URLs, or reuse a flattened on-device asset mirror.

**In 2.3.0:** deploy the complete release-matched asset distribution with its directory layout intact. Refresh the full distribution rather than replacing selected files, and invalidate stale caches. Keep all supplied compatibility assets. Obtain the supported distribution and import configuration from your Incode representative; see [Hosting WASM Files](/sdk-reference/web-sdk-2-wasm/#hosting-wasm-files).

Fonts now load separately through URLs relative to the stylesheet. If you copy `base.css`, also deploy its accompanying `assets/` directory in the same relative location. If you inject stylesheet text, resolve its font URLs against the deployed asset location first. Standard bundler imports and stylesheet links that preserve the package layout need no change.

### Document Capture uploads

**Before:** Document Capture could ignore `sendBase64`, so custom upload handling might receive base64 data even when the flag was false or omitted.

**In 2.3.0:** `false` or omission uses file uploads; `true` requests base64 uploads. To retain base64 handling, explicitly set `sendBase64: true`:

```typescript
import { createDocumentCaptureManager } from '@incodetech/core/document-capture';

const manager = createDocumentCaptureManager({
  config: { processingType: 'addressStatement', sendBase64: true },
});
// Subscribe and drive the capture UI, then call manager.stop() on teardown.
```

Check any custom request adapters against the mode you select. See [Document Capture](/sdk-reference/web-sdk-2-module-document-capture/) for supported document types and upload behavior.

### Event and error handling

**Before:** interview-event consumers could filter `code === 'experimentsAssigned'`.

**In 2.3.0:** filter `code === 'experimentAssigned'`. Consumers processing events from several SDK versions should accept both names while older integrations remain active.

Flow and Workflow module-error messages are now optional. Replace unconditional string operations on `state.error` with a fallback after narrowing to `status === 'error'`. `errorCode` and `moduleErrorCode` are optional too. For example:

```typescript
import type { OrchestratedFlowState } from '@incodetech/core/flow';

function flowErrorText(state: OrchestratedFlowState): string | undefined {
  if (state.status !== 'error') return undefined;
  return state.error || 'Verification could not continue.';
}
```

Use localized fallback copy in your application. Stop matching the former `Mandatory consent error` message. Consent cancellation uses the shared error presentation; messages are not stable identifiers. Forward module codes unchanged when calling `errorModule(error?, moduleErrorCode?)`. See [Event Callbacks](/sdk-reference/web-sdk-2-event-callbacks/).

### Video Selfie terminal outcomes

**Before:** custom hosts could assume the recording continued beyond the configured duration or that exhausted validation attempts remained retryable.

**In 2.3.0:** the configured maximum recording duration is enforced. Expiration shows timeout feedback, completes the current recording, and advances after the feedback screen. Exhausted ID or face validation attempts end the attempt; standalone components report an error, while Flow advances the configured journey.

Handle these outcomes in your custom UI and callbacks; do not automatically restart an exhausted attempt. Completion or journey advancement does not establish verification approval. Review the terminal states and actions in [Video Selfie](/sdk-reference/web-sdk-2-module-video-selfie/#terminal-errors).

### Browser support screens

**Before:** an unsupported browser could enter a module without the SDK's browser-support screen.

**In 2.3.0:** SDK components show guidance for unsupported browser environments, including a link-copy action and a choice to continue. Continuing does not make that browser supported. Test any embedded-browser integration against the [Browser Support](/sdk-reference/incode-web-sdk-2-reference/#browser-support) guidance; native WebViews and third-party in-app browsers are treated differently.

### TrueSight diagnostics

**Before:** an enabled TrueSight configuration could collect diagnostics.

**In 2.3.0:** diagnostics are unavailable, and the accepted setup option has no effect. Remove any operational dependency on receiving those diagnostics. Regular SDK analytics remain available. No restoration date or replacement diagnostic collector is specified.

### Removed APIs

These removals take effect in 2.3.0. Imports, custom configuration, or direct calls must be updated before upgrading.

| Previous usage | Replacement or required action |
| --- | --- |
| `@incodetech/core/personhood` and `createPersonhoodManager()` | Remove the import and the Personhood integration. Personhood is unavailable in this release; no equivalent replacement is provided. Do not present another capture module as the same verification capability. |
| `@incodetech/core/document-upload`, its manager, machine, and related types | Use `@incodetech/core/document-capture` for supported generic-document capture/upload. This is not a drop-in replacement for third-ID verification; third-ID capture remains unsupported. |
| `recording.capability` in ID, Selfie, or Authentication config | Remove the custom provider option and its associated contract imports. Use the supported `enableIdRecording` or `enableFaceRecording` option for SDK-managed recording. A custom-provider replacement is not provided. |
| `getVersions()` on `WasmUtilProvider` imported from `@incodetech/core/extensibility` | Remove the call. There is no replacement runtime-version lookup. |

For Document Upload migration, replace `DocumentUploadConfig.documentType` with a supported `DocumentCaptureConfig.processingType` for your actual document use case. Replace `createDocumentUploadManager()` with `createDocumentCaptureManager({ config })`. The old `capture(imageBase64)` submission becomes `setFile(file, previewDataUrl)` in `tutorial` or `capturing`, followed by `accept()` in `preview` and `continue()` after upload success.

The new manager begins in `tutorial`; do not copy the old `load()` call. It does not expose a `load()` method. Use the action/state table in [Document Capture](/sdk-reference/web-sdk-2-module-document-capture/) and update your old `initializing` / `error` handling to its supported states.

### Deprecated APIs in 2.3.0

These APIs remain callable in 2.3.0 and later so existing code keeps compiling, but they no longer do anything. Remove the calls; removal is planned for 3.0.0.

| Previous usage | Replacement or required action |
| --- | --- |
| `isVirtualCamera()` on `WasmUtilProvider` imported from `@incodetech/core/extensibility` | Remove the call. It always returns `false` in 2.3.0 and later. The check runs natively in the WASM pre-capture step, so no replacement call is needed. |

</Accordion>