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 i18n, uiConfig, and theme. Both entry points support flow; their feature-management option types differ as described below.

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 back end creating the session. Core's setup() accepts optional apiURL and token properties. setup() pairs with initializeSession(); the web wrapper requires token up front.
• You need an option the web wrapper does not accept — encryption, tri, or trueSight. 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)
  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. Use true only during local development.
  tri?: { token: string; apiURL: string; autostart?: boolean }; // Optional TRI telemetry config
  trueSight?: { enabled?: boolean };                   // Temporarily unavailable; option accepted for compatibility.
  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 | { clientExperimentId?: string; disableStableId?: boolean; disablePersistence?: boolean; redactedUserInfo?: FeatureManagementRedactedUserInfo };
  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
});

Web setup accepts only clientExperimentId, disableStableId, disablePersistence, and redactedUserInfo in its feature-management object. Core additionally accepts custom, appVersion, and awaitInitialization. Use core setup when you need those fields, and configure presentation as described above; they are not accepted in a web setup object literal in 2.3.0.

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()
  signal?: AbortSignal;     // Optional: abort the activation (e.g. on unmount)
  preloadFlow?: boolean;    // Optional: fetch the flow configuration alongside activation
  awaitFingerprint?: boolean; // Optional: false resolves before the device fingerprint finishes (default true)
});

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

whenSessionFingerprintSettled()

Use with to awaitFingerprint: false. Resolves with the DeviceFingerprintResult after the background fingerprint finishes, or undefined when fingerprinting failed or was skipped. Never rejects. If the fingerprint was already awaited, it resolves immediately with the cached result.

import { initializeSession, whenSessionFingerprintSettled } from '@incodetech/core/session';

const { features } = await initializeSession({ token, awaitFingerprint: false });
renderHome(features);

const fingerprint = await whenSessionFingerprintSettled();
if (fingerprint?.showMandatoryConsent) showConsent(fingerprint.regulationType);

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. setup() does not wait for gate and experiment values to load: it resolves as soon as the HTTP client is ready and the values arrive in the background, so a read made immediately after await setup() may still see the defaults below. When you need a real value that early, call await getIsFeatureManagementInitialized() first, or pass setup({ featureManagement: { awaitInitialization: true } }) to make setup() block until values are loaded. <incode-flow>, <incode-workflow>, and the SDK's own modules never need either: they read after the session identity update, which waits for loading itself. Before values load, 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

Legacy Flow manager

The manager also provides subscribeFlowEvent(listener) for curated milestones. It returns an unsubscribe function; see headless flow events for subscription and teardown.

createFlowManager() from @incodetech/core/flow loads a Flow and exposes manual step navigation. Prefer createOrchestratedFlowManager for automatic module orchestration.

The modern orchestrator instead uses completeModule() and getModuleConfig<T>() for the current module; it has no legacy prevStep()/canPrev contract. Both support getState(), subscribe(), and stop().

See Also

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