Web SDK 2.0 API Reference

Setup

setup()

Initialize the SDK before using any components.

Which setup() do I call?

You call one, never both. Two packages export a setup(), and @incodetech/web's version calls @incodetech/core's for you:

your app ──▶ setup() from '@incodetech/web' ──calls──▶ setup() from '@incodetech/core'
                adds i18n, uiConfig, theme               apiURL, token, wasm, encryption, …

your app ──▶ setup() from '@incodetech/core'            (headless — the web layer is never loaded)

Start from what you render:

The web wrapper forwards every shared option to core unchanged, then adds the four presentation options core has no concept of: i18n, uiConfig, flow, and theme.

When you deliberately use core's setup() with web components

Two things pull integrators back to the core entry point even when they render components:

• You want setup() to run before the session token exists, so WASM warmup overlaps with your backend creating the session. Core's apiURL and token are both optional and it pairs with initializeSession(); the web wrapper requires token up front.
• You need an option the web wrapper does not accept — encryption, hostingApp, tri, trueSight, or videoSelfie. End-to-end encryption is the common case; see End-to-End Encryption.

That combination works, and the examples throughout these docs use it. Just wire the presentation layer yourself, because core's setup() cannot:

The silent case is worth repeating: a standalone <incode-selfie> or <incode-id> set up through core skips the dashboard theme with no error. If your branding comes from the Incode dashboard rather than setUiConfig, use the web setup().

setup() from @incodetech/core

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

await setup({
  apiURL?: string;                                     // API base URL
  token?: string;                                      // Session token (one-shot convenience — delegates to initializeSession)
  customHeaders?: Record<string, string>;
  timeout?: number;                                    // Request timeout (ms). No deadline when omitted.
  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).
  flow?: false | { preload?: boolean; mergeConfig?: boolean }; // Flow-backed config for standalone modules
  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
  trueSight?: { enabled?: boolean };                   // Default enabled. Set { enabled: false } to opt out of diagnostics.
  featureManagement?: boolean | FeatureManagementSetupOptions; // Default true. Set false to opt out entirely.
  environment?: 'development' | 'staging' | 'production';      // Default 'production'. Feature-management targeting only.
});

The canonical activation pattern is two calls — setup({ apiURL }) first, then initializeSession({ token }) once the session token is known. See initializeSession() below. Passing token to setup is a one-shot convenience that delegates to initializeSession internally.

FeatureManagementSetupOptions

Pass this object form instead of true to configure identity and privacy. The defaults are already conservative: no customer API key is used, and identity starts from an SDK-generated ID rather than anything you supply.

setup() from @incodetech/web

Use this one with the web components. apiURL and token are both required here, so create the session before you call it.

import { setup } from '@incodetech/web';

await setup({
  apiURL: string;                                    // Required
  token: string;                                     // Required: session token from createSession()
  customHeaders?: Record<string, string>;
  timeout?: number;
  wasm?: WasmConfig | false;
  ipLookup?: boolean;
  fingerprint?: boolean;
  devMode?: boolean;
  featureManagement?: boolean | FeatureManagementSetupOptions;
  environment?: 'development' | 'staging' | 'production';
  i18n?: I18nOptions;                                // Language and translation overrides
  uiConfig?: UiConfig;                               // Logo, subtitle, asset/animation and loader overrides
  flow?: false | { preload?: boolean; mergeConfig?: boolean };
  theme?: false | { preload?: boolean };             // Dashboard theme, independent of flow
});

createSession()

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

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

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 }

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.

Feature management

@incodetech/core/feature-management is the read surface for the gates, experiments, layers, and dynamic configs evaluated for the current session. The SDK handles initialization and identity itself during setup() and session activation — this subpath only reads. It ships as a separate subpath so integrations that never read a gate do not pay for it.

Incode agrees the gate and experiment keys with you; they are not self-serve.

import {
  getFeatureGate,
  getExperiment,
  getLayer,
  getFeatureDynamicConfig,
  subscribeFeatureManagement,
} from '@incodetech/core/feature-management';

if (getFeatureGate('your_gate_key').enabled) {
  // gated behavior
}

const experiment = getExperiment('your_experiment_key');
const variant = experiment.get('variantName', 'control');

const layer = getLayer('your_layer_key');
const timeoutMs = layer.get('timeoutMs', 10_000);

Every function here is graceful and none of them throw. Before setup() finishes, and whenever setup({ featureManagement: false }) disabled the integration, reads resolve to documented defaults: gates return false, experiments and layers return your fallback, and dynamic configs return null. Code that reads a gate stays correct with the integration switched off, so you can disable it without branching.

Components

<incode-flow>

Complete verification flow as a standard Web Component.

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

FlowConfig

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

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: complete catalog of every web component and headless manager with import paths
• Web Components: tag-table reference for vanilla / framework-agnostic usage
• Module: Selfie, Module: ID, Module: Phone, 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; detailed lifecycle, state, and method documentation for each manager lives in Headless Mode.

For the four most-used headless APIs, see:

• Module: Selfie § API Methods
• Module: ID § API Methods
• Module: Phone § API Methods
• Module: Email § API Methods

See Also

• TypeScript Types: Type definitions
• Headless Mode: Detailed headless API
• Individual Modules: Complete module catalog