> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit SDKなら、ログインやゲームプレイ、セッションのアクティビティを範囲限定の認証情報で端末から取得できます。対象ユーザーの紐付けとネットワーク情報はサーバー側で強制適用されます。

不正対策で重要な[イベント](https://docs.didit.me/ja/transaction-monitoring/events.md)の多くはデバイス上で発生します。ログイン、セッション、ゲームプレイのラウンド、そして人間とスクリプトを見分けるタイミングのテレメトリなどです。デバイスレーンを使えば、ブラウザにAPIキーを置かずにこれらを送信できます。

バックエンドが1人のユーザーに限定された短期間のみ有効なクレデンシャルを発行し、アプリはそれを使ってイベントを送信します。

## フロー

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

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

**2. デバイスから送信する**

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

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

イベントは、サーバーから送信されたイベントとまったく同じ[ルール](https://docs.didit.me/ja/transaction-monitoring/event-rules.md)によってエンリッチされ、集計され、評価されます。

## クレデンシャルの発行

> [!NOTE]
>
> 発行するには、アプリケーションで[イベントの取り込み](https://docs.didit.me/ja/transaction-monitoring/events.md)が有効になっている必要があります。無効になっている間、このエンドポイントは書き込みができないクレデンシャルを渡す代わりに、`{"code": "event_monitoring_disabled"}`とともに`403`を返します。

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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`が完全に一致する必要があります。 |

## 送信

```bash theme={null}
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はリクエストから導出され、ルール評価ではこれらのサーバー側で導出された値がクライアントからのヒントより優先されます。ルールのエビデンスには、その差異が[フィールドソース](https://docs.didit.me/ja/transaction-monitoring/event-rules.md#エビデンス)として記録されます。
* **カテゴリのスコープ。** `session`にスコープされたクレデンシャルでは`payment`イベントを送信できず、`400`で拒否されます。
* **使用回数の上限。** バッチではイベントごとに1回分を消費するため、500件のイベントを含むバッチを1回分として扱い、10回まで使用できるクレデンシャルの上限をすり抜けることはできません。
* **オリジンのバインド。** `bind_to_origin`が設定されている場合、`Origin`が一致しないリクエストは拒否されます。`Origin`がまったくないリクエストも拒否されます。

## バッチ処理

```bash theme={null}
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件のイベントを送信でき、項目ごとの結果は[サーバーのバッチエンドポイント](https://docs.didit.me/ja/transaction-monitoring/events.md#バッチ)と同じです。フラッシュのデフォルトとしては、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`も一時的なエイリアスとして受け付けます。

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

## レーンの選択

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

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

## 次のステップ

> [card] [イベントの取り込み](https://docs.didit.me/ja/transaction-monitoring/events.md)
>
> エンベロープ、カテゴリ、保持期間、冪等性について説明します。

> [card] [イベントに対するルール](https://docs.didit.me/ja/transaction-monitoring/event-rules.md)
>
> ベロシティ、比率、シーケンス、相関の各ルールについて説明します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.