sumsub-integrate-dint-standalone

Sumsub — Device Intelligence 独立接入（无 WebSDK）

在没有 Sumsub 验证组件的自有页面上运行 Device Intelligence (DI)，例如登录、注册、密码重置、2FA 和结账页面。直接嵌入 Fisherman JS 模块（npm @sumsub/fisherman），在用户执行操作时采集设备信息，并向 Sumsub 确认该操作，以便筛查设备欺诈（机器人、模拟器、VPN/代理、重复使用的设备、多账号）。

这是 Sumsub 的 持续监控 / KYC 前置接入路径。如果页面已经显示 Sumsub WebSDK，请停止操作——DI 已内置其中，请改用 sumsub-integrate-dint-websdk。

⚠️ 仅限沙盒令牌

集成过程中不要接受或使用生产环境的 App Token / secret。务必从 https://cockpit.sumsub.com/checkus/home?sbx=true 获取一对沙盒令牌——Connect Sumsub to your AI agent -> Build & configure -> Generate token。创建时令牌和 secret 只会显示一次；关闭对话框前请复制两者。此处的 curl 示例使用 sbx: 令牌；预检会通过检查 sbx: 前缀来强制执行这一要求。有关更深入的身份验证机制，请参阅：sumsub-api-auth。

开始之前 — 将 DI 融入现有应用

DI 应该看起来像是原本就属于他们的代码库——采用他们的框架、组件、样式和约定。不要覆盖现有应用来搭建新项目，也不要引入新的设计系统。先充分了解代码库以便与之保持一致，然后只询问无法推断的信息：

• 要筛查哪个操作？ 适合接入 DI 的高价值提交操作——登录、注册、提现、结账、2FA、密码重置。（把你在其路由 / 组件中找到的操作列出来作为建议。）
• 后端在哪里？ 能生成行为令牌并为第 3 阶段确认请求签名的服务器文件 / 路由——HMAC 必须留在服务器端。如果他们只有前端（SPA，没有后端），请说明需要一个服务器端点，并提出在其技术栈中添加一个最精简的端点。
• 现有的 Sumsub 接入情况？ 他们是否已经调用 Sumsub / 配置了 App Token + secret、externalUserId 约定或 webhook 接收器？复用现有配置，不要重复添加。
• 如何管理 secret / 环境变量？ 沿用他们现有的 SUMSUB_APP_TOKEN / SUMSUB_SECRET_KEY 管理方式（.env、secret 管理器、配置服务）——集成期间仅使用沙盒值。
• 使用 TypeScript 还是 JS？ 遵循代码库的选择；不要给 JS 项目添加 TS，反之亦然。

将所选操作映射到对应的第 3 阶段确认事件：

操作	第 3 阶段确认事件
登录 / 注册 / 密码重置 / 2FA	平台事件
资金流转（转账、提现、存款、付款）	平台事件 + 金融交易
同时创建申请人的 KYC 前置注册	KYC 前置 create-applicant
访客 / 高价值结账	金融交易

先从 阶段 0（预检） 开始，确认工作区具备 DI 权限，再编写任何代码。然后针对他们的文件实现阶段 1–4：按照其后端风格添加令牌路由，在现有提交处理程序中调用 fisherman.fingerprint()（失败时放行），并在服务器端执行确认请求，事件类型按所选操作映射。只修改必要内容；遵循周围代码的风格。

一图看懂整个流程

 ┌─────────────────────────────┐  ┌──────────────────────────────────────┐
 │ 1. Browser hits your page    │─▶│ Your backend: POST .../accessTokens/  │
 │    (login / signup form)     │  │ behavior {sessionId} → {token}        │
 └─────────────┬───────────────┘  └──────────────────────────────────────┘
               │ behavior access token
 ┌─────────────▼───────────────┐
 │ 2. Browser: @sumsub/fisherman│  ← init(token) → fingerprint() on submit
 │    captures the device       │     returns { visitorId }
 └─────────────┬───────────────┘
               │ user submits (login succeeds / account created)
 ┌─────────────▼───────────────┐  ┌──────────────────────────────────────┐
 │ 3. Your backend confirms the │─▶│ Sumsub runs DI analysis on the event  │
 │    event w/ captured device  │  │ (platform event / txn / applicant)    │
 └─────────────┬───────────────┘  └──────────────────────────────────────┘
               │ verdict + device signals
 ┌─────────────▼───────────────┐  ← Dashboard → Transactions (User
 │ 4. You read results / act    │     platform event); or webhook
 └──────────────────────────────┘

重点：采集设备信息本身不会触发任何操作，只有在服务器端确认事件（阶段 3）后才会生效。单独采集不会产生判定结果——只有确认调用才会让 Sumsub 执行分析。

词汇（请准确理解——这些术语至关重要）

术语	含义	由谁设置
sessionId	关联键。 将一个 DI 会话中的所有指纹和事件关联起来，也是生成行为令牌时使用的会话，因此 Stage 3 的确认操作可在服务端将捕获的设备与事件关联起来，且请求正文中无需包含设备字段。	你的后端——每个逻辑会话生成一个，不透明且唯一。
deviceBindingId	可选的替代关联 ID。Sumsub 正在将设备关联方式从 sessionId 迁移到 deviceBindingId；默认流程中不需要此 ID。如果使用它：将其传给 fingerprint()，生成令牌时使用它，并在确认请求正文的 applicant.device.deviceBindingId 中发送。	你的前端——每个操作生成一个新的 crypto.randomUUID()。
linkedId	可选——将指纹与某个实体关联（你的用户 ID／申请人 ID）。	前端（可选）。
visitorId	fingerprint() 返回的设备标识符；会显示在结果中。使用独立确认流程时，不要转发它——令牌的会话会将采集结果与事件关联起来。	由 Fisherman 返回。

Stage 0 — 预检

scripts/preflight.sh 会在你编写任何前端代码之前， 对工作区进行机器验证：

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

检查项	验证内容
behavior_token	HMAC 签名已获接受，且工作区已启用 Device Intelligence——会生成真实的短时效行为令牌（生成后丢弃，并自行过期；不会修改其他内容）
levels	验证级别已存在。仅警告——只有预 KYC 确认流程（create-applicant）需要验证级别；平台事件无需此级别也可正常运行

所有检查均通过（PASS）或通过并带有警告（PASS+WARN）时，退出码为 0；任何检查失败时，退出码为 10。behavior_token 返回 403 通常意味着该工作区的 DI 权限未启用——此权限不能自行开通；请联系你的 CSM 或 [email protected]， 申请启用 Device Intelligence，并提供你的 clientId（Dashboard 左上角）和环境（sandbox／production）。进入 Stage 1 前，请解决所有失败项。

Stage 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（WebSDK 教程中的空请求正文快捷方式不适用于此处）。请参阅 examples/behavior-token.sh。
• 响应：{ "token": "_act-jwt-..." }——JWT 位于 token 字段中，不是 accessToken。（与 WebSDK 访问令牌端点不同，行为令牌不包含 userId。）
• TTL 默认为 1800s。每个会话按需生成；不要全局缓存。

在后端将其接入受身份验证保护的路由（例如 POST /api/di/token），由该路由 生成／查找 sessionId、签名、调用 Sumsub，并将响应中的 token 返回给浏览器。

Stage 2 — 前端：使用 Fisherman 采集设备信息

npm i @sumsub/fisherman --save

// Shape only — the full impl (fail-open try/catch, React StrictMode teardown) is in
// examples/fisherman-vanilla.html and examples/fisherman-react.tsx.
import { init, destroy } from '@sumsub/fisherman'

// init once when the page / form mounts — getBehaviorToken() calls your Stage-1 route
const fisherman = await init({
  token: await getBehaviorToken(),
  baseUrl: 'https://api.sumsub.com',          // region-specific API host
  accessTokenUpdateHandler: getBehaviorToken, // refresh near expiry
  onError: () => destroy(),                   // never let DI block your form
})

// on the user action (e.g. login submit) — gate, fresh deviceBindingId, then confirm server-side
if (fisherman?.isDeviceIntelligenceEnabled) {
  const deviceBindingId = crypto.randomUUID()
  await fisherman.fingerprint({ deviceBindingId /*, linkedId: userId */ })
  // Fisherman posts the capture under the token's session — your Stage-3 confirm
  // call needs only the same accessToken to tie this device to the event.
}
destroy() // re-init for the next action

规则：

• 仅当 isDeviceIntelligenceEnabled 为真时才调用 fingerprint()——如果工作区未启用 DI， 则静默跳过。
• 每个操作都使用新的 deviceBindingId。 采集结果与确认调用之间的关联由令牌的 sessionId 完成，而非此 ID——只有采用 deviceBindingId 迁移路径时，才需要在确认请求正文中回传此 ID（Stage 3）。
• DI 绝不能阻塞实际流程——用 try/catch 包装，失败时继续放行。
• 操作完成后调用 destroy()；开始下一个操作时重新调用 init()。通过 accessTokenUpdateHandler 刷新令牌（或手动调用 updateAccessToken(newToken)）。

可直接运行的起步示例：examples/fisherman-vanilla.html、 examples/fisherman-react.tsx。

阶段 3 — 后端：使用捕获的设备确认事件

告知 Sumsub 操作已发生；捕获的设备会通过令牌的会话一同传递。选择与操作匹配的调用 — 所有调用都使用你的标准 App Token + HMAC 签名（签名内容为 ts + "POST" + path + body，与其他 Sumsub API 调用完全相同），并额外携带行为访问令牌作为 ?accessToken= 查询参数，以便 Sumsub 将捕获的设备关联到事件。accessToken 不会取代签名 — 它只是随请求一同传递：

操作	端点	文档
登录 / 注册 / 密码重置 / 2FA	POST /resources/applicants/-/kyt/txns/-/data?accessToken=…	平台事件
金融交易	POST /resources/applicants/-/kyt/txns/-/data?accessToken=…	金融交易
KYC 前注册（创建申请人）	创建申请人时传入 levelName + accessToken + externalUserId	KYC 前检查

设备如何关联：确认调用需使用 App-Token + HMAC 签名，并且携带与 ?accessToken= 相同的行为访问令牌。Sumsub 会在服务端通过令牌签发时所用的会话，将捕获的指纹关联到事件（它会根据你的 externalUserId 重建密钥；令牌用于限定会话范围）。你无需在请求体中放入 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 前流程，如果你需要 Advanced IP verification，还要将 creationTrackingData.ip 添加到申请人信息中，然后请求执行申请人检查以触发 DI 分析。

阶段 4 — 查看结果

• **Dashboard：**Transactions and Travel Rule → Transactions，按 User platform event 类型筛选 → 打开对应行 → 查看设备详情和风险标签。
• **Webhooks：**订阅交易 / 事件审核 Webhook，以便通过程序进行拦截（签名验证规则与 WebSDK 技能相同 — 请对原始字节进行验证）。
• 设备风险标签和评分使用与 WebSDK 路径相同的目录： references/standalone-flow.md。完整信号 定义位于 sumsub-integrate-dint-websdk 技能的 references/device-signals.md 中（安装该技能即可获取该文件）。

由你决定哪些设备标签应触发拦截（拒绝 / 升级验证），哪些仅供参考 （记录日志）。

沙盒测试

• 沙盒没有真实设备信号；Fingerprint 使用模拟数据。在 init 时使用 simulationConfig（FpSimulationConf）选项，可强制设置特定信号以获得确定的测试结果。
• 在沙盒中运行完整流程（令牌 → 指纹 → 确认），并确认 Dashboard 中出现 User platform event 交易。

上线检查清单

• 后端生成行为令牌（/accessTokens/behavior），使用请求体签名，并为每个会话分配唯一的 sessionId。
• 令牌端点受身份验证保护（只有经过身份验证的上下文才能生成令牌）。
• 前端采用故障放行策略——Fisherman 出错绝不会阻止登录或注册。
• 行为令牌中每个会话的 sessionId 都是唯一的——它用于将采集到的设备与确认调用关联起来（请求体中不需要设备字段）。
• 在服务端确认事件（平台事件／事务／申请人），以便 Sumsub 实际运行分析——仅采集不会产生判定结果。
• 从控制面板／webhook 读取结果，而不是从浏览器读取。
• 将生产环境的 App Token 和 secret 存储在生产环境的存储中；沙盒值留在开发环境中。

另请参阅

• sumsub-integrate-dint-websdk — 页面已嵌入 Sumsub WebSDK widget 时使用的 DI。
• sumsub-integrate-websdk — 基础 KYC WebSDK 嵌入方案（此处复用其令牌签名和 webhook 模式）。
• sumsub-api-auth — 所有 Sumsub 技能共用的 HMAC 签名。
• scripts/preflight.sh — 工作区验证器（在阶段 1 之前运行）。
• references/standalone-flow.md — 概念、事件类型、结果读取方式、KYC 前置流程和金融事务变体。
• 开始使用 Device Intelligence，生成访问令牌，@sumsub/fisherman — 如果本文档与实际情况不符，请以这些权威来源为准。