sumsub-integrate-dint-websdk

Sumsub — 通过 WebSDK 实现设备智能

为已集成 Sumsub WebSDK 的项目添加设备智能（DI）。DI 是欺诈检测层，可捕获底层设备／浏览器信号（设备指纹、机器人／自动化、VPN／代理、模拟器、无痕模式、重复使用的设备），并将其作为设备风险标签附加到申请人，从而用于风险评分。

负责采集的 JS 模块名为 Fisherman（npm 包 @sumsub/fisherman）——只是名称不同，指的是同一项功能。在 WebSDK 内部，你几乎不需要直接接触它；SDK 会随附并负责驱动它。

⚠️ 仅使用沙盒令牌

集成期间，不要接受或使用生产环境的 App Token／secret。务必从 https://cockpit.sumsub.com/checkus/home?sbx=true 获取一对沙盒凭据——Connect Sumsub to your AI agent -> Build & configure -> Generate token。令牌和 secret 只会在创建时显示一次；关闭对话框前请复制并保存两者。相邻技能中的辅助脚本会通过检查 sbx: 前缀来强制执行此要求；此处的 curl 配置示例也默认使用沙盒凭据。 深入了解身份验证机制：sumsub-api-auth。

生命周期一图览

 ┌───────────────────────────────┐  ← one-time, in the dashboard
 │ 1. "Capture device data" on    │     (verification level settings)
 │    on the verification level   │
 └───────────────┬───────────────┘
                 │
 ┌───────────────▼───────────────┐  ← your existing sumsub-integrate-websdk
 │ 2. WebSDK launches as usual    │     code. NOTHING new on the frontend.
 │    (same access token)         │
 └───────────────┬───────────────┘
                 │ the SDK auto-inits Fisherman with that token,
                 │ fingerprints the device, attaches it to the applicant
 ┌───────────────▼───────────────┐  ┌─────────────────────────────────┐
 │ 3. Sumsub computes device      │─▶│ Device risk labels on the       │
 │    signals + risk labels       │  │ applicant; feed risk scoring    │
 └───────────────┬───────────────┘  └─────────────────────────────────┘
                 │
 ┌───────────────▼───────────────┐  ← server reads the applicant /
 │ 4. You read the verdict +      │     receives the webhook (same as
 │    device signals server-side  │     the base WebSDK flow)
 └────────────────────────────────┘

核心要点：**对于标准 WebSDK 集成，DI 只需在控制面板中切换开关，无需编写新代码。**以下第 3–4 阶段介绍的是高级路径（自行渲染）及读取结果的详细信息。

第 1 阶段 — 在审核等级中启用设备采集

只有在验证等级设置中启用 “Capture device data” 时，DI 才会自动随 WebSDK 2.0 和 Mobile SDKs 一同运行。在控制面板中：打开相应等级 → Device intelligence 部分 → 勾选 Capture device data。如果找不到此设置，说明工作区尚未开通 DI——请联系 Sumsub 开通该产品后再继续。

可选的 BYOK：你可以在 DevSpace → Integrations → Fingerprint 下提供自己的 Fingerprint Pro 凭据（公开 + secret API 密钥），让设备数据通过你的 Fingerprint 账户采集。不使用 BYOK 时，系统会使用 Sumsub 自己的凭据——两种方式都可以；只有在你已使用 Fingerprint Pro 时，BYOK 才有意义。

所需配置到此为止。重新启动现有的 WebSDK 流程，即可开始采集设备数据。

第 2 阶段 — SDK 内自动运行的生命周期（无需编写代码）

启用 “Capture device data” 后，WebSDK 会使用与 sumsub-integrate-websdk 令牌端点生成的同一个访问令牌：

1. SDK 配置加载后，针对 SDK 的 API 主机初始化 Fisherman。
2. 每次步骤转换时对设备进行指纹识别，并将其绑定到当前的 (applicantId, attemptId)。
3. 在等级转换时重新初始化（attemptId 会发生变化），因此多等级流程会为每个等级创建新的设备绑定。
4. 在后续调用中将生成的设备 ID 转发到后端，以便将采集到的数据关联到申请人。

你无需编写、配置或调用其中任何内容。列出这些信息是为了帮助你在日志／网络流量中识别相关活动（/di/info、/bhv/... 事件 POST、X-External-Device-Fingerprint 请求标头）。

阶段 3 —— 高级：自行渲染／无头接线

仅当你不使用预构建的 snsWebSdk 小组件，而是自行调用验证 API 时才适用。此时，Fisherman 的生命周期由你负责。请仿照 SDK 自身的行为——参见 examples/fisherman-self-render.ts：

// Shape only — the full impl (single-active-session class, attemptId re-init,
// try/catch fail-open, header forwarding) is in examples/fisherman-self-render.ts.
import { init, destroy, type Fisherman } from '@sumsub/fisherman'

let fisherman: Fisherman | undefined // module-level singleton

// init once with the SDK access token + region API host
fisherman = await init({ token, baseUrl, onError: () => { destroy() /* re-init after token refresh */ } })

// on each step transition — gate, then fingerprint bound to (applicantId, attemptId)
if (fisherman?.isDeviceIntelligenceEnabled) {
  const { visitorId } = await fisherman.fingerprint({
    linkedId: applicantId,
    deviceBindingId: `${applicantId}-${attemptId}`, // MUST change per level
  })
  // forward visitorId as the X-External-Device-Fingerprint header on the API calls that follow
}

SDK 遵循的关键规则，你也必须遵循：

• 双层门控。SDK 会根据配置级标志 config.deviceIntelligenceSettings.enabled 对 init() 本身进行门控——如果该级别未启用 DI，就不会调用 init()。接着，它会根据运行时标志 fisherman.isDeviceIntelligenceEnabled（来自 /di/info）对每次 fingerprint() 进行门控。两者都要仿照：配置标志为 false 时跳过 init；除非运行时标志为 true，否则绝不调用 fingerprint（否则会报错／浪费调用）。
• 级别切换时（attemptId 发生变化），在下一次 fingerprint() 之前先调用 destroy()，再重新调用 init()，以便设备绑定到正确的级别。
• 将返回的 visitorId 作为 X-External-Device-Fingerprint 请求头，传递给采集后发起的验证 API 调用。（此请求头用于设备／统计信息增强——实际的申请人绑定是上文按尝试生成的 deviceBindingId（applicantId-attemptId），而不是此请求头。）

阶段 4 —— 读取设备信号

DI 不会改变你读取判定结果的方式——它会对结果进行增强。继续遵循基础 WebSDK 技能中的服务端为准原则（webhook + 经过身份验证的申请人 GET），并同时读取设备数据。

在控制面板中：

• 申请人个人资料 → Devices 标签页 — 查看所有出现过的设备及其风险标签。
• 已完成的验证 → Device Check 区块。
• Transactions → 设备行 → View device details。

通过 API／webhook：设备风险标签位于申请人记录中，而不在 webhook 负载中。applicantReviewed webhook 只携带判定结果（reviewResult）——将其视为触发信号，然后在服务端读取申请人（使用与基础技能相同的 App-Token + HMAC 身份验证），这里通过你的 externalUserId 定位：

USER_ID="<your-externalUserId>"   # for a Sumsub applicant id instead: /resources/applicants/<applicantId>/one
PATH_Q="/resources/applicants/-;externalUserId=${USER_ID}/one"
TS=$(date -u +%s)
SIG=$(printf '%s%s%s' "$TS" "GET" "$PATH_Q" \
      | openssl dgst -sha256 -hmac "$SUMSUB_SECRET_KEY" -hex | awk '{print $NF}')
curl -sS --fail-with-body -H "X-App-Token: $SUMSUB_APP_TOKEN" -H "X-App-Access-Ts: $TS" \
     -H "X-App-Access-Sig: $SIG" -H "X-Agent-Source: sumsub-skills" \
     -H "X-Agent-Source-Ver: 1.5.0" \
     "https://api.sumsub.com${PATH_Q}"

此 GET 请求的可运行版本：examples/read-device-results.sh。

完整的设备信号／风险标签目录及其显示位置： references/device-signals.md。

沙盒测试

• 沙盒没有真实的设备信号——Fingerprint 为模拟数据。设备仍会被采集，风险标签也仍会显示，但数值是合成的。
• 为获得确定性的测试结果，该模块支持在 init 时通过 simulationConfig（FpSimulationConf）强制指定信号；这仅适用于自行渲染的路径。预构建的 WebSDK 会自行处理沙盒模拟。
• 运行一次完整的沙盒 WebSDK 验证（参见基础技能的测试文档），并确认申请人的 Devices 标签页中显示了设备。

上线检查清单

• 生产级别已启用“Capture device data”（该设置按级别、按工作区配置——在沙盒中启用不会应用到生产环境）。
• 你的服务端从申请人记录／webhook 读取设备风险标签，而不是从浏览器读取。
• 如果你根据设备风险控制访问，已确定哪些标签会阻止访问，哪些仅供参考（references/device-signals.md）。
• BYOK Fingerprint 密钥（如使用）是生产工作区中的生产密钥；沙盒中仅使用沙盒密钥。
• 仅适用于自行渲染的路径：已通过真实沙盒运行验证 isDeviceIntelligenceEnabled 门控、按 attemptId 重新初始化，以及 X-External-Device-Fingerprint 转发。

另请参阅

• sumsub-integrate-websdk — 此技能所依托的基础 WebSDK 嵌入方案（令牌端点、生命周期、Webhook）。
• sumsub-integrate-dint-standalone — 适用于没有 WebSDK 小组件的页面（登录／注册／结账）的 Device Intelligence。
• sumsub-api-auth — 所有 Sumsub 技能共用的 HMAC 签名。
• references/device-signals.md — 设备风险 标签及其显示位置。
• examples/fisherman-self-render.ts — 高级无头接线方案。
• examples/read-device-results.sh — 在服务端读取 申请人信息（包括设备风险标签）。
• Device Intelligence 文档 和入门指南 — 若此技能内容过时，请以这些权威来源为准。