Width Web SDK

把 Width 身份验证(KYC / KYB / Liveness)嵌入你的 Web 应用。纯前端 ES module,无任何运行时依赖。

安装

npm install @width-com/web-sdk
# 或
pnpm add @width-com/web-sdk

测试版:npm install @width-com/web-sdk@beta

快速开始

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

// 1) 从你的后端拿 accessToken(见下方「accessToken 必须由后端获取」)
const { sdkToken } = await fetch('/your-backend/sdk-token').then(r => r.json());

// 2) 启动验证
widthWebSdk
  .init(sdkToken)
  .withConf({
    apiKey:     'ak_your_public_api_key',
    domainId:   'your_domain_id',
    email:      '[email protected]',
    customerId: 'cust_internal_id',
    mode:       'modal',   // 'modal'(默认) | 'newtab'(可选)
  })
  .on('idCheck.onApplicantVerificationCompleted', (p) => {
    // 验证完成。p.reviewResult.reviewAnswer: 'GREEN'(通过) | 'RED'(拒绝)
    // p.executionId: 建议上报到自己后端做留痕
  })
  .on('idCheck.onApplicantSubmitted', (p) => {
    // 已提交,进入异步审核;稍后用 p.executionId 查结果
  })
  .on('idCheck.onError', (e) => {
    // 失败。e.code: 'INVALID_INPUT' | 'SDK_ERROR' | 'WORKFLOW_FAILED'
  })
  .onMessage((type) => {
    if (type === 'width.onCancelled') { /* 用户主动关闭窗口 */ }
  })
  .build()
  .launch();   // 自托管 modal / newtab,无需提供 DOM 容器

验证界面为亮色主题(当前版本不支持自定义主题 / logo)。

API

widthWebSdk.init(accessToken)

开始一条链式配置。accessToken(即 sdkToken)由你的后端获取,不要在前端暴露 apiKey。

.withConf(conf)

| 参数 | 类型 | 必填 | 说明 | |---|---|:--:|---| | apiKey | string | ✓ | 公开 API key(ak_xxx) | | domainId | string | ✓ | 业务域 / BU 标识 | | email | string | ✓ | 终端用户邮箱 | | customerId | string | ✓ | 你内部的用户 ID | | mode | 'modal' \| 'newtab' | | 打开方式,默认 modal | | zIndex | number | | modal 遮罩层级,默认 9999;仅当被页面上更高层级的元素(如客服悬浮窗)盖住时才需调高 |

.on(eventName, callback)

注册单个事件监听(事件见下)。

.onMessage(callback)

(type, payload) => void,接收所有事件(含用户取消 width.onCancelled)。

.build().launch()

build() 生成实例,launch() 启动验证(自托管 modal / newtab,无需 DOM 容器),返回 sessionHandle。 实例另有 .close() 关闭当前窗口。

验证结果(事件)

整个 session 在终态触发一次,按事件分支处理:

| 事件 | 含义 | 关键 payload | |---|---|---| | idCheck.onApplicantVerificationCompleted | 验证完成,有最终结论 | reviewResult.reviewAnswer = GREEN(通过) / RED(拒绝)、executionId | | idCheck.onApplicantStatusChanged | 状态变更(与上一个同时触发,二选一监听) | 同上 | | idCheck.onApplicantSubmitted | 已提交,进入异步审核 | executionId | | idCheck.onError | 失败 | code、error、executionId? | | width.onCancelled(经 onMessage) | 用户主动关闭窗口 | — |

onError.code:

| code | 含义 | 可重试 | |---|---|:--:| | INVALID_INPUT | 启动参数缺失 / 非法 | ✗ | | SDK_ERROR | 网络超时 / 内部异常 | ✓ | | WORKFLOW_FAILED | 流程以非成功状态结束 | ✗ |

按 code 决定是否给重试入口;error 文本仅用于日志,不要直接展示给终端用户。

accessToken 必须由后端获取

accessToken 应由你的后端调用 Width 的 sdk.credentials 拿到后再下发给前端 —— apiKey 不应出现在客户端调用 credentials(会有 CORS,且不应暴露在浏览器)。

浏览器 ──①请求──▶ 你的后端 ──②sdk.credentials──▶ Width
浏览器 ◀──③sdkToken── 你的后端
浏览器 ──④widthWebSdk.init(sdkToken)...launch()──▶

父页面 CSP

若父页面启用了 CSP,需在 frame-src 加入 Width 托管页域名(具体域名向 Width 技术支持确认)。

排错

| 现象 | 原因 | 解决 | |---|---|---| | 窗口不出现 / iframe 加载失败 | 你的域名未加入 Width 后台 Allowed Origins | 联系 Width 加白名单 | | onError 报 INVALID_INPUT | apiKey/domainId/email/customerId 缺失或非法 | 四项均必填,确认都传了 | | Domain not configured | domainId 与后台业务域不匹配 | 用 sdk.credentials 返回的 domains 里的 id | | CSP 拒绝 iframe | 父页 frame-src 未含托管页域 | 在 CSP 加入托管页域 |

联系

接入问题请联系 Width 技术支持。