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