sumsub-integrate-dint-websdk

Sumsub — WebSDK を介したデバイスインテリジェンス

Sumsub WebSDK をすでに組み込んでいるプロジェクトに、デバイスインテリジェンス（DI）を追加します。DI は、不正検出レイヤーとして、デバイスやブラウザーの低レベルなシグナル（デバイスフィンガープリント、ボット／自動化、VPN／プロキシ、エミュレーター、シークレットモード、デバイスの再利用）を取得し、リスクスコアリングに使われるデバイスリスクラベルとして申請者に紐付けます。

データを取得する JS モジュールは Fisherman（npm @sumsub/fisherman）と呼ばれています。同じ機能を別の名前で呼んでいるだけです。WebSDK 内では、ほとんどの場合、直接操作する必要はありません。SDK が同梱し、制御します。

⚠️ サンドボックストークンのみ

統合作業では、本番用の App Token／シークレットを受け入れたり、使用したりしないでください。 https://cockpit.sumsub.com/checkus/home?sbx=true からサンドボックス用のペアを必ず入手してください。Sumsub を AI エージェントに接続 -> Build & configure -> Generate token の順に選択します。トークンとシークレットは作成時に一度だけ表示されるため、ダイアログを閉じる前に両方コピーしてください。同階層のスキルにあるヘルパースクリプトは 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 — レベルでデバイス情報の取得を有効にする

DI は、検証レベルの設定で「Capture device data」が有効になっている場合に限り、WebSDK 2.0 と Mobile SDK に自動的に組み込まれます。ダッシュボードで、対象のレベルを開き、Device intelligence セクションの Capture device data にチェックを入れます。この設定が表示されない場合、そのワークスペースでは DI がプロビジョニングされていません。続行する前に Sumsub に連絡し、製品を有効にしてもらってください。

任意の BYOK：DevSpace → Integrations → Fingerprint で独自の Fingerprint Pro 認証情報（公開 API キーとシークレット API キー）を指定すると、Fingerprint アカウントでデバイス情報を取得できます。BYOK を使わない場合は、Sumsub 独自の認証情報が使用されます。どちらでも機能し、BYOK が必要なのは、すでに Fingerprint Pro を利用している場合だけです。

必要な設定はこれですべてです。既存の 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 が従っている、必ず守るべき主なルール：

• 2 層のゲートがあります。SDK はまず、設定レベルのフラグ config.deviceIntelligenceSettings.enabled で init() 自体を制御します。そのレベルで DI がオフの場合、init() は呼び出されません。次に、実行時フラグ fisherman.isDeviceIntelligenceEnabled（/di/info から取得）で各 fingerprint() を制御します。両方を再現してください。設定フラグが false の場合は初期化をスキップし、実行時フラグが true でない限り fingerprint() を呼び出さないでください（エラーになるか、呼び出しが無駄になります）。
• レベルが切り替わった場合（attemptId が変わった場合）、次の fingerprint() の前に destroy() を実行してから、もう一度 init() を実行します。これにより、デバイスが正しいレベルに紐付けられます。
• 取得後に続く検証 API 呼び出しでは、返された visitorId を X-External-Device-Fingerprint ヘッダーとして渡してください。（このヘッダーはデバイス／統計情報の補完用です。実際の申請者の紐付けには、上記の試行ごとの 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 ウィジェットのないページ（ログイン／登録／チェックアウト）でのデバイスインテリジェンスについて説明しています。
• sumsub-api-auth — すべての Sumsub スキルで共通して使われる HMAC 署名について説明しています。
• references/device-signals.md — デバイスリスクの ラベルと、それらが表示される場所について説明しています。
• examples/fisherman-self-render.ts — 高度なヘッドレス構成の例です。
• examples/read-device-results.sh — 申請者の情報（デバイスリスクラベルを含む）をサーバー側で読み取ります。
• Device Intelligence のドキュメント およびはじめに — このスキルの内容にずれがある場合に参照する公式情報源です。