sumsub-integrate-dint-standalone

Sumsub — Device Intelligence 単独利用（WebSDK なし）

Sumsub の認証ウィジェットがない独自ページ（ログイン、サインアップ、パスワードリセット、2FA、チェックアウト）で、**Device Intelligence（DI）**を実行します。Fisherman JS モジュール（npm @sumsub/fisherman）を直接埋め込み、ユーザーの操作時にデバイス情報を取得し、その操作を Sumsub に確認することで、デバイス詐欺（ボット、エミュレーター、VPN／プロキシ、デバイスの再利用、複数アカウントの作成）をスクリーニングできるようにします。

これは Sumsub の継続的モニタリング／KYC 前のフローです。ページにすでに Sumsub WebSDK が表示されている場合は、ここではなく sumsub-integrate-dint-websdk を使用してください。DI は WebSDK に組み込まれています。

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

統合の作業中に、本番環境の App Token／シークレットを受け取ったり使用したりしないでください。https://cockpit.sumsub.com/checkus/home?sbx=true からサンドボックスのペアを必ず取得してください。Connect Sumsub to your AI agent -> Build & configure -> Generate token の順に進みます。トークンとシークレットは作成時に一度だけ表示されるため、ダイアログを閉じる前に両方をコピーしてください。ここに記載されている curl の例では sbx: トークンを想定しており、プリフライトでも sbx: のプレフィックスを確認します。認証の詳しい仕組みについては、sumsub-api-auth を参照してください。

開始前 — DI を既存のアプリに組み込む

DI は、フレームワーク、コンポーネント、スタイル、規約に至るまで、最初からそのコードベースの一部だったかのように見える必要があります。**既存アプリに新しい土台を追加したり、新しいデザインシステムを導入したりしないでください。**既存のコードに合わせられるだけの情報をリポジトリから確認し、推測できない点だけを質問してください。

• どの操作をスクリーニングしますか？ DI を組み込む重要度の高い送信操作（ログイン、サインアップ、出金、チェックアウト、2FA、パスワードリセット）を確認します。ルートやコンポーネントから見つけたものを候補として提示してください。
• バックエンドはどこにありますか？ ビヘイビアトークンを発行し、ステージ 3 の確認を署名できるサーバーファイル／ルートを特定します。HMAC は必ずサーバー側に置いてください。フロントエンドのみの構成（SPA、バックエンドなし）の場合は、サーバーエンドポイントが必要であることを伝え、使用中のスタックで最小限のものを追加することを提案してください。
• Sumsub はすでに導入されていますか？ Sumsub の呼び出しがあるか、App Token とシークレットが設定済みか、externalUserId の規約や Webhook の受信先があるかを確認します。既存のものを再利用し、重複させないでください。
• シークレットや環境変数はどのように管理していますか？ SUMSUB_APP_TOKEN／SUMSUB_SECRET_KEY には、既存の方法（.env、シークレットマネージャー、設定サービス）を使用してください。統合中はサンドボックスの値のみを使用します。
• TypeScript と JS のどちらですか？ リポジトリに合わせてください。JS のプロジェクトに TypeScript を追加したり、その逆を行ったりしないでください。

選択した操作を、ステージ 3 の確認イベントに対応付けます。

操作	ステージ 3 の確認イベント
ログイン／サインアップ／パスワードリセット／2FA	プラットフォームイベント
資金移動（送金、出金、入金、支払い）	プラットフォームイベント + 金融トランザクション
申請者も作成する KYC 前のサインアップ	KYC 前の申請者作成
ゲスト／高額チェックアウト	金融トランザクション

コードを書く前に、まず**ステージ 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	相関キーです。 1 つの DI セッション内のすべてのフィンガープリントとイベントを結び付けます。また、動作トークンの発行時に使われるセッションでもあります。そのため、Stage-3 の確認では、リクエストボディにデバイス情報を含めずに、サーバー側で取得したデバイスをイベントに関連付けられます。	バックエンド — 論理セッションごとに 1 つ生成します。値は不透明かつ一意にしてください。
deviceBindingId	省略可能な代替の関連付け ID です。Sumsub はデバイスの関連付けに使う ID を sessionId から deviceBindingId に移行中です。デフォルトのフローでは必須ではありません。使用する場合は、fingerprint() に渡し、この ID を使ってトークンを発行し、確認リクエストのボディ内の 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 が有効になっていることを検証します。実際の短い TTL の動作トークンを発行します（破棄され、自動的に期限切れになります。ほかのものは変更されません）。
levels	検証レベルが存在することを確認します。警告のみ — 検証前の確認パス（create-applicant）でのみ必要です。プラットフォームイベントは検証レベルなしで動作します。

すべてが PASS、または PASS と WARN の場合の終了コードは 0、FAIL が 1 つでもある場合は 10 です。behavior_token で 403 が返る場合、通常はワークスペースでDI の利用権限が無効になっています。セルフサービスでは有効にできません。CSM または [email protected] に連絡し、clientId（ダッシュボードの左上に表示）と環境（sandbox／production）を伝えて、Device Intelligence の有効化を依頼してください。Stage 1 に進む前に、すべての FAIL を解消してください。

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 を使用します。 取得情報と確認呼び出しの相関付けには、この ID ではなくトークンの sessionId を使います。確認リクエストのボディに deviceBindingId を含める必要があるのは、移行パスを利用する場合のみです（Stage 3）。
• DI によって実際のフローを決してブロックしないでください — try/catch で囲み、失敗しても処理を続行してください。
• アクションの後に destroy() を呼び出し、次のアクションの前に再度 init() を呼び出します。accessTokenUpdateHandler でトークンを更新するか、手動で updateAccessToken(newToken) を呼び出してください。

実行可能なサンプルは、examples/fisherman-vanilla.html と examples/fisherman-react.tsx です。

Stage 3 — バックエンド：取得したデバイスとイベントを紐付ける

アクションが発生したことを Sumsub に伝えます。取得したデバイス情報はトークンの セッションを通じて引き継がれます。アクションに合った呼び出しを選んでください。いずれも 標準の App Token + HMAC 署名（他のすべての Sumsub API 呼び出しと同様に、 ts + "POST" + path + body に署名）を使用し、さらに behavior access token を ?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 で署名し、さらに 同じ behavior access token を ?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 分析を 開始します。

Stage 4 — 結果を確認する

• ダッシュボード： Transactions and Travel Rule → Transactions を開き、type を User platform event で絞り込んでから、行を開いてデバイスの詳細とリスクラベルを確認します。
• Webhook： トランザクション／イベントの審査済み Webhook を登録して、プログラムで制御します（署名の検証ルールは WebSDK スキルと同じです。生のバイト列を検証してください）。
• デバイスのリスクラベルとスコアリングは、WebSDK 経由の場合と同じカタログです： references/standalone-flow.md。シグナルの定義全体は sumsub-integrate-dint-websdk スキルの references/device-signals.md にあります（このファイルを使うには、そのスキルをインストールしてください）。

どのデバイスラベルをブロック対象（拒否／追加認証）にし、どれを情報提供用（ログ記録のみ）にするかは、 ご自身で決定してください。

サンドボックスでのテスト

• サンドボックスには実際のデバイスシグナルがありません。Fingerprint はシミュレーションされます。 再現可能なテスト結果を得るには、init の simulationConfig（FpSimulationConf）オプションを使って、 特定のシグナルを強制的に設定してください。
• サンドボックスで一連のフロー（トークン → フィンガープリント → 確認）を実行し、ダッシュボードに User platform event トランザクションが表示されることを確認してください。

リリース前チェックリスト

• バックエンドで behavior トークン（/accessTokens/behavior）を発行し、body に署名します。セッションごとに一意の sessionId を使用します。
• トークンエンドポイントを認証で保護します（認証済みのコンテキストからのみ発行できます）。
• フロントエンドはフェイルオープンにします。Fisherman のエラーによってログインやサインアップがブロックされることはありません。
• behavior トークンにはセッションごとに一意の sessionId を設定します。これによって、キャプチャしたデバイスと confirm 呼び出しが関連付けられます（body にデバイスフィールドは不要です）。
• サーバー側でイベント（プラットフォームイベント／txn／申請者）を確認し、Sumsub が実際に分析を実行するようにします。キャプチャするだけでは判定結果は生成されません。
• 結果はブラウザーではなく、ダッシュボード／Webhook から取得します。
• 本番用の App Token とシークレットを本番用ストアに保存し、サンドボックスの値は開発環境に残します。

関連項目

• sumsub-integrate-dint-websdk — ページに Sumsub WebSDK ウィジェットがすでに埋め込まれている場合の DI。
• sumsub-integrate-websdk — 基本的な KYC WebSDK の埋め込み（ここで再利用するトークン署名や Webhook のパターン）。
• sumsub-api-auth — すべての Sumsub スキルで共通する HMAC 署名。
• scripts/preflight.sh — ワークスペース検証ツール（Stage 1 の前に実行してください）。
• references/standalone-flow.md — 概念、イベントタイプ、結果の取得方法、KYC 前および金融取引バリエーション。
• Get started with Device Intelligence、Generate access token、@sumsub/fisherman — このスキルの内容にずれが生じた場合の信頼できる情報源です。