📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

## Setup

### setup()

Initialize the SDK before using any components:

TypeScript

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

await setup({
  apiURL: string;                                      // Required: API base URL
  token?: string;                                      // Optional: session token (one-shot convenience — delegates to initializeSession)
  customHeaders?: Record<string, string>;
  timeout?: number;                                    // Request timeout (ms)
  wasm?: WasmConfig | false;                           // WASM warmup (see WASM Configuration)
  encryption?: boolean | { mgf1?: 'sha1' | 'sha256' }; // End-to-end encryption (locked at boot)
  hostingApp?: string;                                 // Optional fingerprint hosting-app identifier
  ipLookup?: boolean;                                  // Default true. Set false to skip the third-party IP lookup (api.ipify.org).
  fingerprint?: boolean;                               // Default true. Set false to skip device-fingerprint submission (transition flag).
  devMode?: boolean;                                   // Default false. Set true in local development to silence the devtools detector.
  tri?: { token: string; apiURL: string; autostart?: boolean }; // Optional TRI telemetry config
});
```

The canonical activation pattern is two calls — `setup({ apiURL })` first, then `initializeSession({ token })` once the session token is known. See [`initializeSession()`](https://developer.incode.com/docs/web-sdk-2-reference#initializesession) below. Passing `token` to `setup` is a one-shot convenience that delegates to `initializeSession` internally.

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `apiURL` | `string` | ❌ | API base URL. Omit when every API actor is overridden via `.provide()` (advanced). |
| `token` | `string` | ❌ | Session token. One-shot convenience that delegates to `initializeSession({ token, hostingApp })`. Prefer the explicit two-call form: `setup({ apiURL })` then [`initializeSession({ token })`](https://developer.incode.com/docs/web-sdk-2-reference#initializesession). The two-call form lets you start `setup` (including WASM warmup) before the token is known. |
| `customHeaders` | `Record<string, string>` | ❌ | Headers to attach to every SDK request. |
| `timeout` | `number` | ❌ | Request timeout in milliseconds. |
| `wasm` | `WasmConfig | false` | ❌ | WASM warmup. Omit to skip preload (loads lazily on first selfie/ID capture). Pass an object to warm up with CDN defaults plus any overrides. Pass `false` to explicitly disable. See [WASM Configuration](https://developer.incode.com/docs/web-sdk-2-wasm). |
| `encryption` | `boolean | { mgf1?: 'sha1' | 'sha256' }` | ❌ | Enable end-to-end encryption for SDK traffic. Independent of `token` — can be enabled before a session token is known. Not a self-serve flag — your Incode account team provisions the environment and gives you the dedicated `apiURL` and `mgf1` scheme. Locked at boot (call `reset()` to change later) and requires the WASM binary transport. See [End-to-End Encryption](https://developer.incode.com/docs/web-sdk-2-e2ee) for the full walkthrough including API-key transmission, MGF1 schemes, and failure modes. |
| `hostingApp` | `string` | ❌ | Hosting app identifier forwarded to the fingerprinting service. |
| `ipLookup` | `boolean` | ❌ | Controls the third-party public-IP lookup (`api.ipify.org`). Default `true` (lookup enabled). Set `false` to opt out — no external call to ipify, at the cost of a less-precise fingerprint. Privacy-friendly for deployments where outbound calls to third-party services are restricted. |
| `fingerprint` | `boolean` | ❌ | Controls client-side device-fingerprint submission (`POST /omni/add/device-fingerprint`). Default `true`. Set `false` to skip it entirely — also blanks the fingerprint hash captured during selfie/ID/authentication verification. **Transition flag:** with `fingerprint: false`, the SDK does not auto-inject the mandatory-consent step in `flow`/`workflow` (no regulation data to base it on) — handle consent yourself if this applies to your integration. |
| `devMode` | `boolean` | ❌ | Disables the browser devtools detector for local development. Default `false`. Set `true` only during local development — the detector feeds an anti-fraud signal and must stay on in production. **Do not ship `devMode: true`.** WASM console logging is a separate flag (`wasm.showLogs`). See [WASM Configuration](https://developer.incode.com/docs/web-sdk-2-wasm). |
| `tri` | `{ token: string; apiURL: string; autostart?: boolean }` | ❌ | Transactional Risk Intelligence (TRI) telemetry. Provide `token` (a short-lived SDK token from `createTRISession`, not the org API key) and `apiURL` (the TRI ingest endpoint). TRI starts automatically unless `autostart: false` — use `false` to defer collection until after a consent gate, then call `startTRI()` from `@incodetech/core/tri`. Omitting this field opts out; no collectors start. |

### createSession()

Create a verification session (call from your backend for production):

TypeScript

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

const session = await createSession(apiKey, {
  configurationId: string;   // Required: Flow configuration ID from dashboard
  language?: string;         // Optional: Language code (e.g., 'en-US')
  externalId?: string;       // Optional: Your user reference ID
});

// Returns: { token: string; interviewId: string; ... }
```

### initializeSession()

Activate a session by attaching the token to the HTTP client and pre-loading session-scoped state (feature flags, device fingerprint, analytics flush). Call once you have a session token — typically right after `createSession()` (or after your backend returns the token).

TypeScript

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

await initializeSession({
  token: string;            // Required in application code: the session token from createSession()
  hostingApp?: string;      // Optional: hosting-app identifier forwarded to fingerprinting
  signal?: AbortSignal;     // Optional: abort the activation (e.g. on unmount)
});

// Returns: { features, disableIpify, fingerprintSuccess, fingerprintResult }
```

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | ✅ | Session token returned by `createSession()`. Application code should always pass this explicitly. |
| `hostingApp` | `string` | ❌ | Hosting-app identifier forwarded to the fingerprinting service. |
| `signal` | `AbortSignal` | ❌ | Cancellation signal — useful for unmount-aborts in single-page apps. |

Results are cached per token: calling `initializeSession` again with the same token is a no-op; calling with a different token resets the cache and re-initializes from scratch. Idempotent across concurrent callers — a second in-flight call with the same arguments awaits the first.

## Components

### `<incode-flow>`

Complete verification flow as a standard Web Component.

TypeScript

```typescript
// Side-effect import registers the custom element
import '@incodetech/web/flow';
import '@incodetech/web/flow/styles.css';
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `FlowConfig` | ✅ | Flow configuration object |
| `onFinish` | `(result?: FinishStatus) => void` | ✅ | Called when flow completes |
| `onError` | `(error: string | undefined, errorCode?: number) => void` | ❌ | Called when an error occurs |

#### FlowConfig

`apiURL` is configured via `setup()`, not in `FlowConfig`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | ✅ | Session token from `createSession()` (token-based variant) |
| `apiKey` (or `clientId`) 
\+ `configurationId` | `string` | ✅ (alt) | Self-loading variant — component creates its own session. Avoid in production. |
| `lang` | `string` | ❌ | Language code (e.g. `'en-US'`) |
| `enableHome` | `boolean` | ❌ | Show the SDK's built-in home screen |
| `authHint` | `string` | ❌ | QR/auth hint when re-entering a flow |
| `urlUuid` | `string` | ❌ | QR anti-phishing token from URL |
| `wasmConfig` | `WasmConfig` | ❌ | WASM configuration for ML features |
| `spinnerConfig` | `SpinnerConfig` | ❌ | Loading spinner customization |
| `disableDashboardTheme` | `boolean` | ❌ | Disable dashboard theme |
| `onFlowEvent` | `(event: FlowEvent) => void` | ❌ | Curated flow milestones |
| `onModuleLoading` | `(moduleKey: string) => void` | ❌ | Called when module starts loading |
| `onModuleLoaded` | `(moduleKey: string) => void` | ❌ | Called when module finishes loading |
| `onWasmWarmup` | `(pipelines: string[]) => void` | ❌ | Called when WASM warmup begins |
| `onUrlUuidRefreshed` | `(urlUuid: string) => void` | ❌ | New `urlUuid` available |

### Other components

The SDK ships 20+ web components in addition to `IncodeFlow` — selfie, ID capture, phone, email, signature, consent, eKYC/eKYB orchestrators, and more. Rather than duplicate them here, see:

- [Individual Modules](https://developer.incode.com/docs/web-sdk-2-individual-modules) — complete catalog of every web component and headless manager with import paths
- [Web Components](https://developer.incode.com/docs/web-sdk-2-web-components) — tag-table reference for vanilla / framework-agnostic usage
- [Module: Selfie](https://developer.incode.com/docs/web-sdk-2-module-selfie-1), [Module: ID](https://developer.incode.com/docs/web-sdk-2-module-id-capture), [Module: Phone](https://developer.incode.com/docs/web-sdk-2-module-phone), [Module: Email](https://developer.incode.com/docs/web-sdk-2-module-email) — deep-dive reference pages for the four most-used capture modules, including config tables, state machines, and full API surfaces

## Headless Managers

Every module ships a corresponding `createXxxManager` factory for headless integrations. The full catalog (manager name, core import, what it does) lives in [Individual Modules](https://developer.incode.com/docs/web-sdk-2-individual-modules); detailed lifecycle, state, and method documentation for each manager lives in [Headless Mode](https://developer.incode.com/docs/web-sdk-2-headless-mode).

For the four most-used headless APIs, see:

- [Module: Selfie § API Methods](https://developer.incode.com/docs/web-sdk-2-module-selfie-1#api-methods)
- [Module: ID § API Methods](https://developer.incode.com/docs/web-sdk-2-module-id-capture#api-methods)
- [Module: Phone § API Methods](https://developer.incode.com/docs/web-sdk-2-module-phone#api-methods)
- [Module: Email § API Methods](https://developer.incode.com/docs/web-sdk-2-module-email#api-methods)