> ## 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 的限定范围凭证，从设备采集登录、游戏行为和会话活动；主体绑定与网络上下文均在服务端强制执行。

对欺诈有影响的大多数[事件](https://docs.didit.me/zh/transaction-monitoring/events.md)都发生在设备上：登录、会话、游戏回合，以及能够区分真人与脚本的时序遥测数据。设备通道无需在浏览器中放置 API 密钥即可发送这些事件。

你的后端会签发一个短期有效、仅限单个用户使用的凭证，应用使用该凭证提交事件。

## 流程

**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/zh/transaction-monitoring/event-rules.md)进行评估。

## 签发凭证

> [!NOTE]
>
> 签发凭证要求应用已开启[事件接入](https://docs.didit.me/zh/transaction-monitoring/events.md)。在其关闭期间，该 endpoint 会返回 `403` 及 `{"code": "event_monitoring_disabled"}`，而不会签发一个永远无法用于写入事件的凭证。

```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 | 每个**事件**计一次使用，而非每个请求计一次。 |
| `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" }
  }'
```

请注意，payload 本身**不包含**以下两项：API 密钥和主体。这两项均由服务器端强制校验。

## 服务器端强制执行的约束

* **主体绑定。** 凭证在签发时即限定于一个 `vendor_data`。请求体中的 `subject` 块会被覆盖，因此被篡改的客户端无法写入其他用户的时间线。
* **网络上下文。** IP 地址、用户代理、accept-language 和 origin 均从请求中推导得出。在规则评估时，这些由服务器推导的值优先于客户端提供的任何提示。规则证据会以[字段来源](https://docs.didit.me/zh/transaction-monitoring/event-rules.md#证据)的形式记录两者之间的差异。
* **类别范围。** 限定为 `session` 的凭证无法提交 `payment` 事件，此类请求会被拒绝，并返回 `400`。
* **使用次数预算。** 批量请求按每个事件消耗一次使用次数，因此 500 个事件的批量请求不能被当作单次使用，从而绕过只有 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": [ { "…": "…" }, { "…": "…" } ] }'
```

每次刷新最多发送 500 个事件，逐项结果与[服务端批量 endpoint](https://docs.didit.me/zh/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`。

## 选择通道

| | 设备通道 | 服务端通道 |
| - | - | - |
| endpoint | `POST /v1/events/` | `POST /v3/events/` |
| 鉴权 | `X-Monitoring-Token` | `x-api-key` |
| 主体 | 与凭证绑定 | 位于 payload 中 |
| 最适合 | 登录、会话、游戏过程、遥测数据 | 支付、争议、账本衍生事件、历史回填 |

两种通道生成的事件记录完全相同，运行的规则也完全相同。只要不存在终端用户，就应使用服务端通道。

## 后续步骤

> [card] [事件接入](https://docs.didit.me/zh/transaction-monitoring/events.md)
>
> 包括信封结构、类别、保留期和幂等性。

> [card] [事件上的规则](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)
>
> 包括速率、比率、序列和关联规则。


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