Web SDK 集成指南

概述

Width Web SDK 为 Web 应用提供即插即用的身份验证流程。支持 KYC 和 KYB 工作流，包括证件采集、活体检测与审核。SDK 自托管：你引入一个包，用链式调用配置它，再调用 launch() — SDK 会自行弹出弹窗或打开新标签页，并通过事件回报结果。无需提供 DOM 容器。它以 ESM 构建发布，自带完整 TypeScript 类型定义，无 peer 依赖。

系统要求

步骤 1：获取会话 token（后端）

Web SDK 从一个一次性会话 token（即 sdkToken）开始。你的服务端向 Width 的 sdk.credentials 接口请求它，再把它交给浏览器。公开的 apiKey 与 domainId 在后续步骤中配置；带密钥的签名只在你的服务端完成。

// 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" }
      ]
    }
  }
}

在后端开一个小接口（例如 /your-backend/sdk-token），把 sdkToken 和 domainId 返回给前端。把从 domains[] 中选定的 domainId 在步骤 3 传入 SDK 配置。

步骤 2：安装 SDK

从 npm 安装。安装后即可按包名 @width-com/web-sdk 引入 — ESM 构建，自带 TypeScript 类型定义，无 peer 依赖。装哪个标签同时决定 SDK 连到哪个环境：按本指南基准，默认（latest）版对应正式环境，@beta 标签版对应 platform（测试）环境。请按你的 apiKey 所属环境选择对应标签，并在上线前确认你装的这一版实际打开的是哪个地址（见下方提示）。

# 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

步骤 3：初始化（快速开始）

用一条链式调用构建验证：init 传入会话 token，withConf 传入配置，用 on / onMessage 订阅事件，再 build().launch()。launch() 会弹出自托管的弹窗或新标签页 — 无需提供 DOM 容器。

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

配置（withConf）

步骤 4：处理验证结果

launch() 成功时返回本次会话的完整核验页 URL，失败时返回空字符串。错误通过 idCheck.onError 回传。

按你订阅的事件分支处理。最终结论由 reviewResult.reviewAnswer 携带，只有两个取值：结论为通过时是 GREEN，其余一律是 RED。

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

每个事件对应一条处理分支：

验证结果参考

最终结论由 reviewResult.reviewAnswer 携带：

方法

事件参考

用 .on(eventName, callback) 注册单个事件，或用 .onMessage((type, payload) => {}) 接收全部。

错误码

在 idCheck.onError 中，payload.code 为以下之一：

浏览器支持

Web SDK 依赖 crypto.randomUUID、ES2020 语法，以及现代的 fetch 与 postMessage。下表是同时具备这三项的最低版本，低于该版本的浏览器不在支持范围内。

故障排查

# 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")