Web SDK Integration Guide

Overview

The Width Web SDK provides a drop-in identity verification flow for web apps. It supports KYC and KYB workflows including document capture, liveness detection, and review. The SDK is self-hosted: you import one package, configure it with a fluent chain, and call launch() — the SDK presents its own modal or new tab and reports the outcome through events. No DOM container is required. It ships as an ESM build with full TypeScript types and no peer dependencies.

Requirements

Step 1: Get a session token (backend)

The Web SDK starts from a one-time session token (the sdkToken). Your server requests it from Width's sdk.credentials endpoint, then hands it to the browser. The public apiKey and domainId are configured in the next steps; the secret signing happens only on your server.

// Server-side request to Width (signed with your secret)
POST {WIDTH_GATEWAY_URL}/gateway?api=sdk.credentials&apiVersion=1.0.0&apiKey={your_apiKey}&sign=...
Content-Type: application/json

{}

// Response — read sdkToken and the domains[] list
{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "data": {
      "sdkToken": "eyJhbGciOi...",
      "domains": [
        { "code": "DEFAULT", "name": "Default", "id": "dom_xxxxxxxx" }
      ]
    }
  }
}

Expose a small backend route (for example /your-backend/sdk-token) that returns the sdkToken and the domainId to your frontend. Pass the chosen domainId from domains[] into the SDK config in Step 3.

Step 2: Install the SDK

Install from npm. After install, import by the package name @width-com/web-sdk — ESM build, TypeScript types included, no peer dependencies. The tag you install also selects the environment the SDK connects to: in this documentation baseline, the default (latest) release targets production and the @beta tag targets the platform (testing) environment. Install the tag that matches the environment your apiKey belongs to, and confirm which address your installed build opens before you ship (see the note below).

# Production (正式环境)
npm install @width-com/web-sdk
# or
pnpm add @width-com/web-sdk
# or
yarn add @width-com/web-sdk

# Testing / beta (测试环境)
npm install @width-com/web-sdk@beta
# or
pnpm add @width-com/web-sdk@beta
# or
yarn add @width-com/web-sdk@beta

Step 3: Initialize (Quick Start)

Build the verification with a fluent chain: init the session token, withConf the configuration, subscribe to events with on / onMessage, then build().launch(). launch() presents the self-hosted modal or new tab — you do not pass a DOM container.

import { widthWebSdk } from '@width-com/web-sdk';

// Get the session token from your backend (sdkToken from sdk.credentials)
const { sdkToken, domainId } =
  await fetch('/your-backend/sdk-token').then(r => r.json());

widthWebSdk
  .init(sdkToken)
  .withConf({
    apiKey:     'ak_your_public_api_key', // required
    domainId,                             // required
    email:      'enduser@example.com',    // required
    customerId: 'cust_internal_id',       // required
    mode:       'modal',                  // 'modal' (default) | 'newtab'
    // eventType: 'KYC_EVENT',            // optional — 'KYC_EVENT' | 'KYB_EVENT'; omit for default routing
  })
  .on('idCheck.onApplicantVerificationCompleted', (payload) => {
    // payload.reviewResult.reviewAnswer: 'GREEN' (approved) | 'RED' (not approved)
  })
  .on('idCheck.onApplicantSubmitted', (payload) => {
    // Submitted; async review in progress
  })
  .on('idCheck.onError', (payload) => {
    // payload.code / payload.error
  })
  .onMessage((type, payload) => {
    if (type === 'width.onCancelled') {
      // User closed the flow
    }
  })
  .build()
  .launch();   // self-hosted modal / new tab — no DOM container needed

Configuration (withConf)

Step 4: Handle the result

launch() returns the full verification-page URL for this session on success, and an empty string on failure. Errors are delivered through idCheck.onError.

Branch on the events you subscribed to. The final verdict is carried by reviewResult.reviewAnswer. It takes exactly two values: GREEN when the outcome is approved, and RED for every other outcome.

.on('idCheck.onApplicantVerificationCompleted', (payload) => {
  const { reviewResult, executionId } = payload;
  if (reviewResult.reviewAnswer === 'GREEN') {
    grantAccess(executionId);
  } else {
    handleNotApproved(executionId);
  }
})

Each event maps to a branch of your handling logic:

Verification result reference

The final verdict is carried by reviewResult.reviewAnswer:

Methods

Events

Subscribe to a single event with .on(eventName, callback), or receive all with .onMessage((type, payload) => {}).

Error Codes

On idCheck.onError, payload.code is one of:

Browser Support

The Web SDK relies on crypto.randomUUID, ES2020 syntax, and a modern fetch / postMessage. The versions below are the earliest that carry all three; anything older is not supported.

Troubleshooting

# Default (latest) build / 默认（latest）版
Content-Security-Policy: frame-src https://identity.width.com;
Permissions-Policy: camera=(self "https://identity.width.com"),
                    microphone=(self "https://identity.width.com"),
                    accelerometer=(self "https://identity.width.com"),
                    gyroscope=(self "https://identity.width.com")

# @beta build / @beta 版
Content-Security-Policy: frame-src https://identity-platform.width.com;
Permissions-Policy: camera=(self "https://identity-platform.width.com"),
                    microphone=(self "https://identity-platform.width.com"),
                    accelerometer=(self "https://identity-platform.width.com"),
                    gyroscope=(self "https://identity-platform.width.com")