sumsub-integrate-dint-websdk

用途

本技能用于为已经通过 Sumsub WebSDK 验证用户的 Web 项目添加设备智能（Device Intelligence，简称 DI，即 Fisherman 模块）。DI 是欺诈检测层，负责采集底层设备与浏览器信号（设备指纹、机器人/自动化、VPN/代理、模拟器、无痕模式、设备复用等），并将这些信号作为设备风险标签附加到申请人上，供风险评分使用。

执行采集的 JS 模块名为 Fisherman（npm 包 @sumsub/fisherman），与设备智能是同一事物的不同名称。在 WebSDK 内部通常无需直接接触它，SDK 会自带并驱动它。

主要能力

在验证级别设置中启用“Capture device data”后，WebSDK 2.0 与移动 SDK 会自动携带设备智能能力。
WebSDK 使用与基础集成相同的访问令牌，自动初始化 Fisherman、在每次步骤切换时对设备进行指纹采集，并绑定到当前（applicantId, attemptId）。
在级别切换（attemptId 变化）时重新初始化，使多级别流程中每个级别获得新的设备绑定。
将生成的设备 id 转发到后端，使采集结果与申请人关联。
支持可选 BYOK：在 DevSpace → Integrations → Fingerprint 中提供自己的 Fingerprint Pro 凭据（公钥 + 密钥 API key），使设备在自有 Fingerprint 账户下采集；不提供则使用 Sumsub 自有凭据。
设备风险标签会落在申请人上，可通过仪表盘（申请人资料 → Devices 标签页、已完成验证 → Device Check 区块、Transactions → 设备行 → View device details）或服务端 API 读取。

使用方式

阶段 1：在级别上启用设备采集

在仪表盘中打开验证级别 → Device intelligence 区块 → 勾选 Capture device data。若看不到该设置，说明工作区尚未开通 DI，需联系 Sumsub 启用。这是全部必需设置，重新启动现有 WebSDK 流程后设备即开始被采集。

阶段 2：SDK 内自动生命周期（无需代码）

启用后，WebSDK 使用现有令牌端点签发的同一访问令牌自动完成：初始化 Fisherman、在步骤切换时指纹采集并绑定到（applicantId, attemptId）、在级别切换时重新初始化、将设备 id 转发到后端。无需编写、配置或调用任何内容。可在日志/网络流量中识别相关请求（/di/info、/bhv/... 事件 POST、X-External-Device-Fingerprint 请求头）。

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

仅在不使用预构建 snsWebSdk 组件、自行驱动验证 API 时需要。此时需自行管理 Fisherman 生命周期，镜像 SDK 行为：

// 仅示意形状——完整实现见 examples/fisherman-self-render.ts
import { init, destroy, type Fisherman } from '@sumsub/fisherman'

let fisherman: Fisherman | undefined // 模块级单例

// 使用 SDK 访问令牌 + 区域 API 主机初始化一次
fisherman = await init({ token, baseUrl, onError: () => { destroy() /* 令牌刷新后重新初始化 */ } })

// 每次步骤切换——先判断门控，再按 (applicantId, attemptId) 绑定进行指纹采集
if (fisherman?.isDeviceIntelligenceEnabled) {
  const { visitorId } = await fisherman.fingerprint({
    linkedId: applicantId,
    deviceBindingId: `${applicantId}-${attemptId}`, // 必须随级别变化
  })
  // 将 visitorId 作为 X-External-Device-Fingerprint 头转发到后续 API 调用
}

关键规则：

双层门控：SDK 在配置级标志 config.deviceIntelligenceSettings.enabled 为 false 时不调用 init()；在运行时标志 fisherman.isDeviceIntelligenceEnabled（来自 /di/info）为 true 前不执行 fingerprint()。需同时镜像这两层。
级别切换（attemptId 变化）时，先 destroy() 再 init()，然后才进行下一次 fingerprint()。
将返回的 visitorId 作为 X-External-Device-Fingerprint 头转发到采集后的验证 API 调用。该头是设备/统计增强，实际申请人绑定是上面的按尝试 deviceBindingId（applicantId-attemptId），而非该头。

阶段 4：读取设备信号

DI 不改变读取判定结果的方式，只是丰富它。保持服务端为唯一事实来源（webhook + 已认证的申请人 GET），并同时读取设备数据。设备风险标签落在申请人上，不在 webhook 载荷中。applicantReviewed webhook 仅携带判定结果（reviewResult），应将其作为服务端读取申请人的触发器（使用与基础技能相同的 App-Token + HMAC 认证），按 externalUserId 查询：

USER_ID="<your-externalUserId>"   # 若使用 Sumsub 申请人 id：/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}"

可运行版本见 examples/read-device-results.sh。完整的设备信号/风险标签目录及其出现位置见 references/device-signals.md。

适用场景

已使用 Sumsub WebSDK 验证用户，希望在不改动前端代码的前提下增加设备欺诈检测。
需要采集设备指纹、识别机器人/自动化、VPN/代理、模拟器、无痕模式、设备复用等风险信号。
需要将设备风险标签纳入风险评分或访问门控决策。
自渲染/无头集成场景下需要自行管理 Fisherman 生命周期。

限制与注意事项

仅使用沙箱令牌：集成期间不得接受或使用生产 App Token/密钥。需从 https://cockpit.sumsub.com/checkus/home?sbx=true 获取沙箱令牌对（Connect Sumsub to your AI agent → Build & configure → Generate token），令牌与密钥仅在创建时显示一次，关闭对话框前需复制两者。
沙箱没有真实设备信号，Fingerprint 为模拟；设备仍会被采集、风险标签仍会出现，但值为合成数据。
确定性测试结果可通过在 init 时传入 simulationConfig（FpSimulationConf）强制特定信号，仅适用于自渲染路径；预构建 WebSDK 自行处理沙箱模拟。
“Capture device data”是按级别、按工作区设置的，沙箱中启用不会延续到生产。
若基于设备风险进行访问门控，需自行决定哪些标签为阻断性、哪些为信息性（见 references/device-signals.md）。
若使用 BYOK Fingerprint 密钥，生产工作区需使用生产密钥，沙箱仅使用沙箱密钥。
自渲染路径需验证 isDeviceIntelligenceEnabled 门控、按 attemptId 重新初始化、X-External-Device-Fingerprint 转发均通过真实沙箱运行验证。

技能介绍

用途