SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sumsub-integrate-websdk

sumsub-integrate-websdk

安全与审计

查看项目

更新于 10-16 10:41

技能介绍

用途

该技能用于指导开发者将 Sumsub 的 KYC（了解你的客户）身份验证功能通过 Sumsub WebSDK 端到端地集成到网站或 Web 应用中。它覆盖从创建工作区中的验证级别（level），到在服务端生成访问令牌，再到前端启动 SDK、处理生命周期事件，最后通过服务端 webhook 确认最终审核结果并据此控制用户权限的完整流程。

主要能力与流程

整个集成生命周期分为五个阶段：

  1. 拥有一个验证级别（level）：每次 SDK 启动都需要引用一个已存在的工作区级别名称（如 basic-kyc-level）。若用户尚无级别，文档建议先与其讨论需求，再通过 sumsub-create-level 技能创建，而不是默认选择。文档给出一个起步流程示例：APPLICANT_DATA（姓名、出生日期、国家、地址）、IDENTITY（护照、身份证、驾照，模式为 any）、SELFIE（videoRequired: passiveLiveness），并建议仅在监管要求时添加居住证明（PROOF_OF_RESIDENCE），仅在需要结构化数据时添加问卷（QUESTIONNAIRE）。

  2. 服务端访问令牌端点：SDK 需要一个由后端使用 App Token 和 secret 生成的短期访问令牌（ttlInSecs，默认 1800 秒），并限定为单个 (userId, levelName) 组合。端点形如 POST https://api.sumsub.com/resources/accessTokens?userId=<...>&levelName=<...>&ttlInSecs=600，请求体为空，认证方式为 App Token + HMAC 签名。文档给出了 curl 签名示例，并强调 userId 应当稳定、不透明（如 UUID 或数据库行 ID，而非邮箱），且与自身认证系统关联，否则会导致重复申请人、用户卡在已提交状态以及无法恢复中断的验证。

  3. 前端 SDK 初始化：通过加载 https://static.sumsub.com/idensic/static/sns-websdk-builder.js 暴露全局 snsWebSdk。需要为容器设置明确的最小高度（如 600px），并挂载一个覆盖加载遮罩，在 idCheck.onReady 时隐藏。文档提供了原生 JavaScript 与 React 组件的代码范例，React 范例处理了两个常见问题：CDN 脚本必须在读取 snsWebSdk 前存在；React 18 严格模式下组件会挂载两次，清理函数必须移除 iframe 或清空容器。

  4. 客户端生命周期事件：文档列举了各类事件（如 idCheck.onReady、idCheck.onApplicantSubmitted、idCheck.onApplicantStatusChanged、idCheck.onError 等）及其用途，并强调这些事件仅为用户体验信号，不能作为权威状态。文档要求至少绑定三个必需处理器：onReady 隐藏遮罩、onApplicantSubmitted 切换到审核中状态、onError 渲染可重试的错误。

  5. 服务端权威数据源：通过 webhook 接收 Sumsub 的事件通知，或在需要时通过服务端 API 主动查询申请人状态。文档强调浏览器端的 onApplicantReviewed 可被伪造，唯一权威信号是服务端 webhook 或经过认证的 GET /resources/applicants/{userId}/one 请求。

使用方式

集成步骤包括：在沙盒环境中创建工作区级别、在后端实现 HMAC 签名的令牌端点、在前端加载 SDK 并启动、绑定客户端事件处理器、配置并验证 webhook 接收器（本地可用 ngrok 暴露端口进行联调）、根据 reviewResult.reviewAnswer（GREEN/RED）控制用户访问。文档提供了签名验证的 Node/Express 示例代码，并提醒验证时需使用原始字节，不能在计算摘要前进行 JSON 解析。

适用场景

适用于需要在网站或 Web 应用中嵌入 Sumsub 身份验证流程的开发者，例如用户注册时的 KYC 审核、合规性身份验证等场景。文档同时给出了 webhook 事件类型（如 applicantCreated、applicantPending、applicantReviewed 等）及其对应处理动作的参考。

限制与注意事项

集成阶段仅使用沙盒令牌，禁止使用生产 App Token 或 secret。生产环境的 webhook 设置必须由人工直接在 Sumsub 控制台中完成，不应通过任何技能创建。webhook 签名密钥与 App Token secret 不同，是独立的 webhook secret，需存储在环境变量中。服务的权威状态应来自 webhook 或主动 API 查询，不应依赖浏览器事件，也不应使用轮询循环。