在已有 Sumsub WebSDK…

当项目已用 Sumsub WebSDK 做用户验证，需要额外捕获设备指纹、检测多账号/设备欺诈并获取设备风险标签时使用。

适用场景

解决思路

1. 在验证 level 设置中启用设备捕获：打开 dashboard 中的 level → Device intelligence 区域 → 勾选 Capture device data；若看不到该设置说明工作区未开通 DI，需联系 Sumsub 开通。
2. 可选 BYOK：在 DevSpace → Integrations → Fingerprint 中填入自己的 Fingerprint Pro 凭据（public + secret API key），让设备捕获走自己的 Fingerprint 账号；不配置则使用 Sumsub 自带凭据，两者都可用。
3. 标准 WebSDK 集成无需新增前端代码：启用 Capture device data 后，WebSDK 会用现有 token endpoint 签发的同一 access token 自动初始化 Fisherman，在每次步骤切换时对设备做指纹并绑定到当前 (applicantId, attemptId)，在 level 切换（attemptId 变化）时重新初始化，并把设备 id 转发给后端。
4. 在日志/网络流量中识别自动生命周期：查找 /di/info、/bhv/... 事件 POST、X-External-Device-Fingerprint 请求头。
5. 仅在自渲染/headless 路径（不使用预构建 snsWebSdk widget、自行驱动验证 API）时才需自行管理 Fisherman 生命周期：用 @sumsub/fisherman 的 init({ token, baseUrl, onError }) 初始化模块级单例，onError 中 destroy() 并在 token 刷新后重新 init。
6. 自渲染路径中实现两层门控：config.deviceIntelligenceSettings.enabled 为 false 时跳过 init()；仅当运行时标志 fisherman.isDeviceIntelligenceEnabled（来自 /di/info）为 true 时才调用 fingerprint()。
7. 自渲染路径中在每次步骤切换时调用 fisherman.fingerprint({ linkedId: applicantId, deviceBindingId: `${applicantId}-${attemptId}` })，deviceBindingId 必须随 level 变化；在 level 切换时先 destroy() 再 init() 再 fingerprint()。
8. 自渲染路径中把返回的 visitorId 作为 X-External-Device-Fingerprint 请求头，附加到后续验证 API 调用上（该头仅用于设备/统计增强，真正的申请人绑定是 per-attempt 的 deviceBindingId）。
9. 在 dashboard 中读取设备信号：申请人资料 → Devices 标签页查看所有设备及风险标签；完成的验证 → Device Check 区块；Transactions → 设备行 → View device details。
10. 通过 API 读取设备风险标签：风险标签落在申请人上而非 webhook payload 中；applicantReviewed webhook 只携带 verdict（reviewResult），应作为触发信号在服务端读取申请人。
11. 用 App Token + HMAC 认证按 externalUserId 读取申请人：构造 PATH_Q="/resources/applicants/-;externalUserId=${USER_ID}/one"，用 openssl dgst -sha256 -hmac "$SUMSUB_SECRET_KEY" 对 TS+GET+PATH_Q 签名，再带 X-App-Token、X-App-Access-Ts、X-App-Access-Sig 请求 https://api.sumsub.com${PATH_Q}。
12. 沙箱测试：沙箱中 Fingerprint 为模拟，设备仍会被捕获、风险标签仍会出现但值为合成数据；自渲染路径可在 init 时传 simulationConfig（FpSimulationConf）强制特定信号，预构建 WebSDK 自行处理沙箱模拟；跑一次完整沙箱 WebSDK 验证并确认设备出现在申请人的 Devices 标签页。
13. 上线前检查：确认生产 level 已启用 Capture device data（按 level、按工作区，沙箱启用不会带到生产）；服务端而非浏览器读取设备风险标签；决定哪些标签阻断、哪些仅提示；BYOK 生产工作区用生产密钥、沙箱只用沙箱密钥；自渲染路径需在真实沙箱运行中验证 isDeviceIntelligenceEnabled 门控、per-attemptId 重新初始化和 X-External-Device-Fingerprint 转发。
14. 集成期间只使用沙箱凭据：从 cockpit.sumsub.com 的沙箱环境生成 App Token 与 secret（Connect Sumsub to your AI agent → Build & configure → Generate token），token 与 secret 仅显示一次，关闭对话框前复制两者；不要使用生产 token/secret。

适用边界 · 注意事项

• 页面没有 WebSDK widget（如登录/注册/结账页）时，应改用 sumsub-integrate-dint-standalone。
• 只需要基础 WebSDK 嵌入本身时，应改用 sumsub-integrate-websdk。
• 工作区未开通 Device Intelligence 产品（level 设置中看不到 Capture device data）时无法继续，需先联系 Sumsub 开通。