在没有 Sumsub 验证组件的自有页面上接入设备指纹风控（…

当页面没有嵌入 Sumsub WebSDK，却需要在登录、注册、改密、2FA、结账等高风险动作上做设备指纹与欺诈筛查时，用 Fisherman JS 模块独立接入 Device Intelligence。

适用场景

解决思路

1. 先确认页面没有嵌入 Sumsub WebSDK；若已嵌入，改用 sumsub-integrate-dint-websdk 技能，因为 DI 已内置其中。
2. 集成期间只使用 sandbox 的 App Token / secret，从 https://cockpit.sumsub.com/checkus/home?sbx=true 的 Connect Sumsub to your AI agent -> Build & configure -> Generate token 生成，token 与 secret 只在创建时显示一次，关闭弹窗前复制两者；curl 示例假定 token 带 sbx: 前缀。
3. 在动手前先读仓库，让 DI 融入现有代码风格：确认要筛查的高价值动作（登录/注册/提现/结账/2FA/改密）、后端能签发 behavior token 并做 Stage-3 确认的位置（HMAC 必须留在服务端，纯前端 SPA 需补一个最小服务端端点）、是否已有 Sumsub 调用/App Token/secret/externalUserId 约定/webhook 接收器、密钥与环境变量的既有管理方式、以及项目用 TypeScript 还是 JS。
4. 按动作映射 Stage-3 确认事件：登录/注册/改密/2FA 用 platform event；资金流动（转账、提现、充值、支付）用 platform event + financial txn；需要同时创建 applicant 的 pre-KYC 注册用 pre-KYC create-applicant；访客/高价值结账用 financial txn。
5. 先运行 Stage 0 预检脚本确认工作区具备 DI 权限：SUMSUB_APP_TOKEN=sbx:... SUMSUB_SECRET_KEY=... bash scripts/preflight.sh；behavior_token 检查验证 HMAC 签名被接受且 Device Intelligence 已启用（会签发一个短 TTL 的 behavior token，自行过期，不改动其他数据），levels 检查为 WARN-only（只有 pre-KYC create-applicant 路径需要 level）；退出码 0 表示全 PASS 或 PASS+WARN，10 表示有 FAIL；behavior_token 返回 403 通常意味着工作区未开通 DI 权限，需联系 CSM 或 support@sumsub.com 并提供 clientId 与环境；所有 FAIL 解决后再进入 Stage 1。
6. Stage 1 后端签发 behavior access token：POST https://api.sumsub.com/resources/accessTokens/behavior，Content-Type: application/json，body 为 {"sessionId": "<your-session-id>", "ttlInSecs": 1800}；用 App Token + HMAC 签名，签名内容为 ts + "POST" + path + body（body 参与签名，WebSDK 技能里的空 body 快捷方式不适用）；响应中 JWT 在 token 字段而非 accessToken；TTL 默认 1800 秒，按会话按需签发，不要全局缓存；把它做成受鉴权保护的后端路由（如 POST /api/di/token），生成或查找 sessionId、签名、调用 Sumsub 并把响应的 token 返回浏览器。
7. Stage 2 前端安装并初始化 Fisherman：npm i @sumsub/fisherman --save；在页面/表单挂载时调用一次 init({ token: await getBehaviorToken(), baseUrl: 'https://api.sumsub.com', accessTokenUpdateHandler: getBehaviorToken, onError: () => destroy() })，其中 getBehaviorToken() 调用 Stage 1 的路由。
8. 在用户动作（如登录提交）时先判断 fisherman?.isDeviceIntelligenceEnabled，为真则生成 crypto.randomUUID() 作为 deviceBindingId，再 await fisherman.fingerprint({ deviceBindingId /*, linkedId: userId */ })；Fisherman 会把采集结果提交到 token 对应会话下，Stage-3 确认只需同一个 accessToken 即可关联设备与事件。
9. 前端规则：用 isDeviceIntelligenceEnabled 做门控，DI 关闭时静默跳过；每次动作使用全新的 deviceBindingId；DI 绝不能阻塞真实流程，用 try/catch 失败开放；动作结束后 destroy()，下次动作重新 init()；通过 accessTokenUpdateHandler 或手动 updateAccessToken(newToken) 刷新 token。
10. Stage 3 后端确认事件：按动作选择端点——登录/注册/改密/2FA 与金融交易都用 POST /resources/applicants/-/kyt/txns/-/data?accessToken=…；pre-KYC 注册则创建 applicant 并带 levelName + accessToken + externalUserId。所有调用都用标准 App Token + HMAC 签名（签 ts + "POST" + path + body），并额外把 behavior access token 作为 ?accessToken= 查询参数传入，accessToken 不替代签名而是与签名并行。
11. Stage 3 关联机制：确认调用由 App Token + HMAC 签名并携带与采集时相同的 behavior access token；Sumsub 在服务端用签发 token 时的 session 把采集到的指纹与事件关联（从 externalUserId 重建 key，token 限定 session）；body 中不要放 visitorId 或 device 块，只需标识用户与事件，例如 {"txnId": "<unique-id-you-generate>", "type": "userPlatformEvent", "applicant": {"externalUserId": "<your-user-id>", "type": "individual"}, "userPlatformEventInfo": {"type": "login"}}。
12. 若走 deviceBindingId 关联迁移路径（默认流程不需要）：签发 token 时带 deviceBindingId，fingerprint() 传同一个值，并在确认 body 的 applicant.device.deviceBindingId 中回传。
13. pre-KYC 场景如需 Advanced IP 验证，在 applicant 中加 creationTrackingData.ip，然后请求 applicant check 以触发 DI 分析。
14. Stage 4 读取结果：在 Dashboard 的 Transactions and Travel Rule -> Transactions 中按类型 User platform event 过滤，打开行查看设备详情与风险标签；或订阅 transaction/event reviewed webhook 做程序化拦截（按 WebSDK 技能同样的规则在原始字节上验签）；设备风险标签与评分目录与 WebSDK 路径一致，完整信号定义见 sumsub-integrate-dint-websdk 技能的 references/device-signals.md；自行决定哪些设备标签是阻断（拒绝/二次验证）哪些仅记录。
15. Sandbox 测试：sandbox 没有真实设备信号，Fingerprint 是模拟的；用 init 的 simulationConfig（FpSimulationConf）强制特定信号以获得确定性结果；在 sandbox 跑完整链路（token -> fingerprint -> confirm）并确认 Dashboard 出现 User platform event 交易。
16. 上线前检查：后端用唯一 per-session sessionId 签发 behavior token 且 body 参与签名；token 端点受鉴权保护；前端失败开放，Fisherman 报错不阻塞登录/注册；每个会话唯一 sessionId 用于关联采集设备与确认调用（body 无需设备字段）；在服务端确认事件（platform event / txn / applicant）以真正触发分析；结果从 Dashboard/webhook 读取而非浏览器；生产 App Token 与 secret 放生产密钥库，sandbox 值只留在开发环境。

适用边界 · 注意事项

• 页面已经嵌入 Sumsub WebSDK 时不要用本技能——DI 已内置在 WebSDK 中，应改用 sumsub-integrate-dint-websdk。
• 集成阶段不要接受或使用生产 App Token / secret，必须使用 sandbox 凭证。
• 纯前端（SPA、无后端）且无法新增服务端端点时无法完成，因为 HMAC 签名与 Stage-3 确认必须留在服务端。