SDKイベント送信 - クライアント側でのイベント取得

不正対策で重要なイベントの多くはデバイス上で発生します。ログイン、セッション、ゲームプレイのラウンド、そして人間とスクリプトを見分けるタイミングのテレメトリなどです。デバイスレーンを使えば、ブラウザにAPIキーを置かずにこれらを送信できます。バックエンドが1人のユーザーに限定された短期間のみ有効なクレデンシャルを発行し、アプリはそれを使ってイベントを送信します。

フロー

モニタリング用クレデンシャルを発行する

バックエンドが、APIキーとユーザーのvendor_dataを指定してPOST /v3/events/sdk-token/を呼び出します。

デバイスから送信する

アプリがX-Monitoring-Tokenヘッダーを付けてPOST /v1/events/(またはPOST /v1/events/batch/)に送信します。

ルールは通常どおり実行される

イベントは、サーバーから送信されたイベントとまったく同じルールによってエンリッチされ、集計され、評価されます。

クレデンシャルの発行

発行するには、アプリケーションでイベントの取り込みが有効になっている必要があります。無効になっている間、このエンドポイントは書き込みができないクレデンシャルを渡す代わりに、{"code": "event_monitoring_disabled"}とともに403を返します。

curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'

{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}

フィールド	デフォルト	備考
`vendor_data`	必須	このクレデンシャルで送信されるすべてのイベントが属する対象者です。
`entity_type`	`individual`	`individual`または`company`です。
`allowed_event_categories`	すべて	漏えいしたクレデンシャルで書き込める範囲を絞り込みます。
`ttl_seconds`	900	60 - 86400です。
`max_uses`	1000	使用回数はリクエスト単位ではなく、イベント単位で1回とカウントされます。
`bind_to_origin`	なし	設定した場合、ブラウザの`Origin`が完全に一致する必要があります。

送信

curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'

ペイロードに含まれていないものに注目してください。APIキーも対象者も含まれていません。どちらもサーバー側で適用されます。

サーバー側で強制される内容

対象のバインド。 クレデンシャルは発行時に1つのvendor_dataにスコープされます。リクエスト本文のsubjectブロックは上書きされるため、改ざんされたクライアントが別のユーザーのタイムラインに書き込むことはできません。
ネットワークコンテキスト。 IPアドレス、ユーザーエージェント、accept-language、originはリクエストから導出され、ルール評価ではこれらのサーバー側で導出された値がクライアントからのヒントより優先されます。ルールのエビデンスには、その差異がフィールドソースとして記録されます。
カテゴリのスコープ。 sessionにスコープされたクレデンシャルではpaymentイベントを送信できず、400で拒否されます。
使用回数の上限。 バッチではイベントごとに1回分を消費するため、500件のイベントを含むバッチを1回分として扱い、10回まで使用できるクレデンシャルの上限をすり抜けることはできません。
オリジンのバインド。 bind_to_originが設定されている場合、Originが一致しないリクエストは拒否されます。Originがまったくないリクエストも拒否されます。

バッチ処理

curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'

1回のフラッシュにつき最大500件のイベントを送信でき、項目ごとの結果はサーバーのバッチエンドポイントと同じです。フラッシュのデフォルトとしては、25件のイベント、5秒、またはページやアプリがバックグラウンドに移ったタイミングが適しています。

バックプレッシャー時に破棄してよいもの

イベントを間引く必要がある場合は、重要度の低いものから間引いてください。次のイベントは破棄しても問題ありません。 session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked 次のイベントは破棄しないでください。最優先でフラッシュしてください。すべてのsecurity、payment、dispute、responsible_gamblingイベント、およびgameplay.bet_placed、gameplay.bet_settled、gameplay.p2p_settlementです。一覧エンドポイントは同じ分類をイベントごとにis_droppableとして返すため、クライアントはハードコードしたコピーではなく、この値に基づいて動作できます。

ヘッダーの互換性

正式なヘッダーはX-Monitoring-Tokenです。すでにトランザクション用の認証情報を保持しているアプリが段階的に移行できるよう、X-Transaction-Tokenも一時的なエイリアスとして受け付けます。

このエイリアスは移行期間用のもので、イベントAPIの一般提供開始前に削除されます。新しいコードではX-Monitoring-Tokenを送信してください。

レーンの選択

	デバイスレーン	サーバーレーン
エンドポイント	`POST /v1/events/`	`POST /v3/events/`
認証	`X-Monitoring-Token`	`x-api-key`
対象	クレデンシャルに紐付く	ペイロード内で指定
適した用途	ログイン、セッション、ゲームプレイ、テレメトリ	決済、チャージバック、台帳から導出されるイベント、バックフィル

どちらも同一のイベントレコードを生成し、同一のルールを実行します。エンドユーザーが介在しない場合は、常にサーバーレーンを使用してください。

次のステップ

イベントの取り込み

エンベロープ、カテゴリ、保持期間、冪等性について説明します。

イベントに対するルール

ベロシティ、比率、シーケンス、相関の各ルールについて説明します。

はじめに

機能

リファレンス

コンソール

SDKイベント送信 - クライアント側でのイベント取得

フロー

クレデンシャルの発行

送信

サーバー側で強制される内容

バッチ処理

バックプレッシャー時に破棄してよいもの

ヘッダーの互換性

レーンの選択

次のステップ

イベントの取り込み

イベントに対するルール

​フロー

​クレデンシャルの発行

​送信

​サーバー側で強制される内容

​バッチ処理

​バックプレッシャー時に破棄してよいもの

​ヘッダーの互換性

​レーンの選択

​次のステップ

イベントの取り込み

イベントに対するルール

フロー

クレデンシャルの発行

送信

サーバー側で強制される内容

バッチ処理

バックプレッシャー時に破棄してよいもの

ヘッダーの互換性

レーンの選択

次のステップ