sumsub-integrate-dint-standalone

用途

本技能用于在自有网页中集成 Sumsub Device Intelligence（设备智能，简称 DI），适用于没有 Sumsub 验证组件的页面，例如登录、注册、密码重置、2FA、结账等。通过直接嵌入 Fisherman JS 模块（npm 包 @sumsub/fisherman），在用户操作时采集设备信息，并在服务端向 Sumsub 确认事件，以便筛查设备欺诈（机器人、模拟器、VPN/代理、设备复用、多账号等）。这是 Sumsub 的持续监控 / 预 KYC 路径。如果页面已展示 Sumsub WebSDK，则 DI 已内置，应改用 sumsub-integrate-dint-websdk。

主要能力

在无 Sumsub 验证组件的自有页面上运行设备智能。
通过 Fisherman JS 模块采集设备指纹。
将采集到的设备与用户操作事件在服务端关联，触发 Sumsub 分析。
支持多种事件类型：平台事件（登录/注册/密码重置/2FA）、金融交易、预 KYC 创建申请人。
结果可通过仪表盘（Transactions）或 webhook 读取。

使用方式

前置要求

集成期间仅使用沙箱令牌，不要使用生产 App Token / secret。需从 https://cockpit.sumsub.com/checkus/home?sbx=true 获取沙箱令牌对（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。令牌和密钥仅在创建时显示一次，关闭对话框前请复制两者。

阶段 0 — 预检

运行 scripts/preflight.sh 机器验证工作区：

SUMSUB_APP_TOKEN=sbx:... SUMSUB_SECRET_KEY=... \
  bash scripts/preflight.sh

检查 behavior_token（验证 HMAC 签名被接受且工作区已启用 DI）和 levels（验证级别存在，仅预 KYC 路径需要）。退出码：全部 PASS 或 PASS+WARN 为 0，任何 FAIL 为 10。behavior_token 返回 403 通常表示工作区未启用 DI 权限，需联系 CSM 或 support@sumsub.com 启用，并提供 clientId 和环境。

阶段 1 — 后端：签发行为访问令牌

独立于 WebSDK 令牌的端点，注意 /behavior 后缀和 JSON 请求体：

POST https://api.sumsub.com/resources/accessTokens/behavior
Content-Type: application/json
{ "sessionId": "<your-session-id>", "ttlInSecs": 1800 }

认证：App Token + HMAC。请求体是签名的一部分——签名 ts + "POST" + path + body。响应：{ "token": "_act-jwt-..." }，JWT 在 token 字段中，而非 accessToken。TTL 默认 1800 秒。按会话按需签发，不要全局缓存。将其作为后端受认证保护的路由（例如 POST /api/di/token）。

阶段 2 — 前端：使用 Fisherman 采集设备

npm i @sumsub/fisherman --save

import { init, destroy } from '@sumsub/fisherman'

const fisherman = await init({
  token: await getBehaviorToken(),
  baseUrl: 'https://api.sumsub.com',
  accessTokenUpdateHandler: getBehaviorToken,
  onError: () => destroy(),
})

if (fisherman?.isDeviceIntelligenceEnabled) {
  const deviceBindingId = crypto.randomUUID()
  await fisherman.fingerprint({ deviceBindingId /*, linkedId: userId */ })
}
destroy()

规则：以 isDeviceIntelligenceEnabled 为条件调用 fingerprint()；每次操作使用新的 deviceBindingId；DI 绝不能阻塞真实流程（try/catch，失败开放）；操作后 destroy()，下次重新 init()；通过 accessTokenUpdateHandler 刷新令牌。可运行示例：examples/fisherman-vanilla.html、examples/fisherman-react.tsx。

阶段 3 — 后端：用采集的设备确认事件

选择与操作匹配的调用，均使用标准 App Token + HMAC 签名，并额外携带行为访问令牌作为 ?accessToken= 查询参数：

登录/注册/密码重置/2FA：POST /resources/applicants/-/kyt/txns/-/data?accessToken=…（平台事件）
金融交易：POST /resources/applicants/-/kyt/txns/-/data?accessToken=…（金融交易）
预 KYC 注册：创建申请人，带 levelName + accessToken + externalUserId

设备关联方式：确认调用使用 App Token + HMAC 签名，并携带与签发时相同的行为访问令牌作为 ?accessToken=。Sumsub 在服务端使用令牌签发时的会话将采集的指纹与事件关联。请求体中不需要 visitorId 或设备块，只需标识用户和事件：

{
  "txnId": "<unique-id-you-generate>",
  "type": "userPlatformEvent",
  "applicant": { "externalUserId": "<your-user-id>", "type": "individual" },
  "userPlatformEventInfo": { "type": "login" }
}

可运行示例：examples/submit-platform-event.sh。金融交易和预 KYC 请求体及完整字段列表见 references/standalone-flow.md。

基于 deviceBindingId 的关联（Sumsub 正在迁移）是例外：签发令牌时带 deviceBindingId，将其传给 fingerprint()，并在 applicant.device.deviceBindingId 发送。默认流程基于 sessionId，不需要这些。

预 KYC 时，如需高级 IP 验证，还需在申请人中添加 creationTrackingData.ip，然后请求申请人检查以触发 DI 分析。

阶段 4 — 读取结果

仪表盘：Transactions and Travel Rule → Transactions，按 type User platform event 筛选，打开行查看设备详情和风险标签。

Webhook：订阅 transaction/event reviewed webhook 以编程方式控制（签名验证规则与 WebSDK 技能相同，基于原始字节验证）。

设备风险标签和评分与 WebSDK 路径相同，见 references/standalone-flow.md。完整信号定义在 sumsub-integrate-dint-websdk 技能的 references/device-signals.md 中。哪些设备标签是阻断性的（拒绝/升级验证）与信息性的（记录）由你决定。

适用场景

登录、注册、密码重置、2FA 等平台事件。
资金移动（转账、提现、存款、支付）等金融交易。
预 KYC 注册并创建申请人。
访客/高价值结账。

限制

集成期间仅使用沙箱令牌，不要使用生产令牌。
沙箱没有真实设备信号，Fingerprint 是模拟的。可使用 init 的 simulationConfig（FpSimulationConf）选项强制特定信号以进行确定性测试。
采集设备本身不产生判定，必须在服务端确认事件（阶段 3）才会触发分析。
结果从仪表盘或 webhook 读取，不从浏览器读取。
生产 App Token 和密钥应放在生产存储中，沙箱值留在开发环境。

上线检查清单

后端签发行为令牌（/accessTokens/behavior），签名请求体，每个会话使用唯一 sessionId。
令牌端点受认证保护。
前端失败开放——Fisherman 错误绝不阻塞登录/注册。
行为令牌中每个会话使用唯一 sessionId——这是将采集设备与确认调用关联的关键。
在服务端确认事件（平台事件/交易/申请人），以便 Sumsub 实际运行分析。
结果从仪表盘/webhook 读取，不从浏览器读取。
生产 App Token 和密钥在生产存储中；沙箱值留在开发环境。

技能介绍

用途