sumsub-integrate-dint-websdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Device Intelligence via the WebSDK

Sumsub — 通过WebSDK实现设备智能

Add Device Intelligence (DI) to a project that already embeds the Sumsub WebSDK. DI is the fraud-detection layer that captures low-level device/browser signals (device fingerprint, bot/automation, VPN/proxy, emulator, incognito, reused-device) and attaches them to the applicant as device risk labels that feed risk scoring.

The JS module that does the capture is called Fisherman (npm

@sumsub/fisherman

) — same thing, different name. Inside the WebSDK you almost never touch it directly; the SDK ships and drives it for you.

为已嵌入Sumsub WebSDK的项目添加设备智能（DI）功能。DI是欺诈检测层，可捕获底层设备/浏览器信号（设备指纹、机器人/自动化工具、VPN/代理、模拟器、隐身模式、重复使用设备），并将这些信号作为设备风险标签关联到申请人，为风险评分提供数据支持。

负责捕获数据的JS模块名为Fisherman（npm包

@sumsub/fisherman

）——两者指代同一功能，只是名称不同。在WebSDK中，你几乎无需直接操作该模块，SDK会自动加载并驱动它运行。

⚠️ Sandbox tokens only

⚠️ 仅使用沙箱令牌

Do not accept or use a production App Token / secret during integration work. Insist on a sandbox pair from https://cockpit.sumsub.com/checkus/devSpace/appTokens — toggle the workspace to Sandbox first, then Create. Token + secret are revealed once at creation; copy both before closing the dialog. Helper scripts in sibling skills enforce this with an

sbx:

prefix check; the curl recipes here assume the same. Deeper auth mechanics:

sumsub-api-auth

集成过程中请勿使用生产环境的应用令牌/密钥。请从https://cockpit.sumsub.com/checkus/devSpace/appTokens获取沙箱令牌对——先将工作区切换为Sandbox，再点击Create。令牌和密钥仅在创建时显示一次，请在关闭对话框前复制两者。同目录下其他技能中的辅助脚本会通过

sbx:

前缀检查强制验证这一点；本文中的curl命令也遵循此规则。更详细的认证机制请参考：

sumsub-api-auth

。

The lifecycle in one picture

生命周期示意图

 ┌───────────────────────────────┐  ← 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)
 └────────────────────────────────┘

The headline: for a standard WebSDK integration, DI is a dashboard toggle, not new code. Stages 3–4 below are the advanced (self-rendered) path and the result-reading details.

 ┌───────────────────────────────┐  ← 仅需在控制台操作一次
 │ 1. 在验证级别开启"捕获设备数据" │     （验证级别设置）
 │    选项                       │
 └───────────────┬───────────────┘
                 │
 ┌───────────────▼───────────────┐  ← 你已有的sumsub-integrate-websdk
 │ 2. WebSDK正常启动             │     代码。前端无需修改任何内容。
 │   （使用相同的访问令牌）       │
 └───────────────┬───────────────┘
                 │ SDK会自动使用该令牌初始化Fisherman，
                 │ 为设备生成指纹并关联到申请人
 ┌───────────────▼───────────────┐  ┌─────────────────────────────────┐
 │ 3. Sumsub计算设备信号和风险标签 │─▶│ 申请人的设备风险标签，为风险评分提供数据 │
 └───────────────┬───────────────┘  └─────────────────────────────────┘
                 │
 ┌───────────────▼───────────────┐  ← 服务器端读取审核结果和
 │ 4. 你在服务器端读取审核结果和   │     设备信号（与基础WebSDK流程一致，
 │    设备信号                   │     可通过Webhook接收）
 └────────────────────────────────┘

核心要点：对于标准WebSDK集成，DI仅需在控制台切换开关，无需编写新代码。以下第3-4阶段为高级（自定义渲染）实现路径和结果读取细节。

Stage 1 — Enable device capture on the level

阶段1 — 在验证级别启用设备捕获

DI rides along automatically in WebSDK 2.0 and the Mobile SDKs only when "Capture device data" is enabled in the verification level settings. In the dashboard: open the level → Device intelligence section → tick Capture device data. If you don't see the setting, DI isn't provisioned for the workspace — contact Sumsub to enable the product before continuing.

Optional BYOK: you can supply your own Fingerprint Pro credentials (public + secret API key) under DevSpace → Integrations → Fingerprint so devices are captured under your Fingerprint account. Without BYOK, Sumsub's own credentials are used — both work; BYOK only matters if you already run Fingerprint Pro.

That's the entire required setup. Re-launch your existing WebSDK flow and devices start getting captured.

仅当验证级别设置中开启「捕获设备数据」选项时，DI才会自动在WebSDK 2.0和移动SDK中运行。操作步骤：在控制台中打开对应验证级别 → 进入设备智能板块 → 勾选捕获设备数据。若未找到该设置，说明当前工作区未启用DI功能，请联系Sumsub启用产品后再继续。

可选BYOK（自带密钥）：你可以在DevSpace → Integrations → Fingerprint中提供自己的Fingerprint Pro凭证（公钥+密钥API密钥），这样设备数据会捕获到你的Fingerprint账户下。若不使用BYOK，将默认使用Sumsub自身的凭证——两种方式均可生效；仅当你已在使用Fingerprint Pro时，BYOK才有实际意义。

以上就是全部必要设置。重新启动你已有的WebSDK流程，设备数据将开始被捕获。

Stage 2 — The automatic in-SDK lifecycle (no code)

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

With "Capture device data" on, the WebSDK, using the same access token your

sumsub-integrate-websdk

token endpoint already mints:

Initializes Fisherman against the SDK's API host once the SDK config loads.
Fingerprints the device on each step transition, binding it to the current
```
(applicantId, attemptId)
```
.
Re-initializes on a level transition (the
```
attemptId
```
changes), so a multi-level flow gets a fresh device binding per level.
Forwards the resulting device id to the backend on subsequent calls so the capture is tied to the applicant.

You do not write, configure, or call any of this. It is listed so you can recognise it in logs / network traffic (

/di/info

, an

/bhv/...

events POST, an

X-External-Device-Fingerprint

request header).

开启「捕获设备数据」后，WebSDK会使用你已有的

sumsub-integrate-websdk

令牌端点生成的相同访问令牌执行以下操作：

加载SDK配置后，针对SDK的API主机初始化Fisherman。
在每个步骤切换时为设备生成指纹，并将其绑定到当前的
```
(applicantId, attemptId)
```
。
在验证级别切换时（
```
attemptId
```
变化）重新初始化，确保多级别流程中每个级别都能获取新的设备绑定。
在后续调用中将生成的设备ID转发到后端，使捕获的数据与申请人关联。

你无需编写、配置或调用任何上述代码。列出这些步骤是为了让你能在日志/网络请求中识别相关操作（如

/di/info

、

/bhv/...

事件POST请求、

X-External-Device-Fingerprint

请求头）。

Stage 3 — Advanced: self-rendered / headless wiring

阶段3 — 高级：自定义渲染/无UI配置

Only relevant if you do not use the prebuilt

snsWebSdk

widget and drive the verification API yourself. Then you own the Fisherman lifecycle. Mirror the SDK's own behaviour — see

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
}

Key rules the SDK follows and you must too:

Two-layer gate. The SDK gates
```
init()
```
itself on the config-level flag
```
config.deviceIntelligenceSettings.enabled
```
— when DI is off for the level it never calls
```
init()
```
. Then it gates each
```
fingerprint()
```
on the runtime flag
```
fisherman.isDeviceIntelligenceEnabled
```
(from
```
/di/info
```
). Mirror both: skip init when the config flag is false, never fingerprint unless the runtime flag is true (it errors / wastes a call).
On a level transition (
```
attemptId
```
changes)
```
destroy()
```
then
```
init()
```
again before the next
```
fingerprint()
```
, so devices bind to the right level.
Forward the returned
```
visitorId
```
as the
```
X-External-Device-Fingerprint
```
header on the verification API calls that follow the capture. (This header is device/stats enrichment — the actual applicant binding is the per-attempt
```
deviceBindingId
```
(
```
applicantId-attemptId
```
) above, not the header.)

仅当你不使用预构建的

snsWebSdk

组件，而是自行调用验证API时，此部分才适用。此时你需要自行管理Fisherman的生命周期。请参考SDK自身的实现逻辑——详见

examples/fisherman-self-render.ts

：

// 仅展示代码结构——完整实现（单活动会话类、attemptId重新初始化、
// try/catch容错、请求头转发）请查看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}`, // 每个验证级别必须更换
  })
  // 在后续的API调用中，将visitorId作为X-External-Device-Fingerprint请求头转发
}

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

双层校验。SDK会先根据配置级别的标志
```
config.deviceIntelligenceSettings.enabled
```
判断是否调用
```
init()
```
——当验证级别未启用DI时，SDK绝不会调用
```
init()
```
。然后，每次调用
```
fingerprint()
```
前都会根据运行时标志
```
fisherman.isDeviceIntelligenceEnabled
```
（来自
```
/di/info
```
）进行校验。请完全遵循这两层校验：当配置标志为false时跳过初始化，仅当运行时标志为true时才执行指纹捕获（否则会报错或浪费请求）。
当验证级别切换时（
```
attemptId
```
变化），先调用
```
destroy()
```
再重新
```
init()
```
，然后再执行下一次
```
fingerprint()
```
，确保设备绑定到正确的级别。
将返回的
```
visitorId
```
作为
```
X-External-Device-Fingerprint
```
请求头，在捕获后的验证API调用中转发。（该请求头用于设备/统计信息补充——实际与申请人绑定的是上述每个尝试的
```
deviceBindingId
```
（
```
applicantId-attemptId
```
），而非请求头。）

Stage 4 — Read the device signals

阶段4 — 读取设备信号

DI does not change how you read the verdict — it enriches it. Keep the server-as-source-of-truth rule from the base WebSDK skill (webhook + authenticated applicant GET), and read the device data alongside it.

In the dashboard:

Applicant profile → Devices tab — every device seen, with risk labels.
Completed verification → Device Check block.
Transactions → a device row → View device details.

Via API / webhooks: the device risk labels land on the applicant, not in the webhook payload. The

applicantReviewed

webhook carries the verdict only (

reviewResult

) — treat it as the trigger to read the applicant server-side (same App-Token + HMAC auth as the base skill), here keyed by your

externalUserId

bash

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.2.0" \
     "https://api.sumsub.com${PATH_Q}"

Runnable version of that GET:

examples/read-device-results.sh

The full device-signal / risk-label catalog and where each surfaces:

references/device-signals.md

DI不会改变你读取审核结果的方式——只会丰富结果内容。请遵循基础WebSDK技能中的「服务器作为唯一可信源」规则（Webhook + 认证后的申请人信息GET请求），并同时读取设备数据。

在控制台中：

申请人档案 → 设备标签页——显示所有检测到的设备及其风险标签。
已完成的验证 → 设备检查区块。
交易记录 → 设备行 → 查看设备详情。

通过API/Webhook：设备风险标签会关联到申请人，而非Webhook payload中。

applicantReviewed

Webhook仅携带审核结果（

reviewResult

）——请将其作为触发信号，在服务器端读取申请人信息（使用与基础技能相同的App-Token + HMAC认证），以下示例使用你的

externalUserId

作为查询键：