客户端事件采集 SDK - 事件提交

对欺诈有影响的大多数事件都发生在设备上：登录、会话、游戏回合，以及能够区分真人与脚本的时序遥测数据。设备通道无需在浏览器中放置 API 密钥即可发送这些事件。你的后端会签发一个短期有效、仅限单个用户使用的凭证，应用使用该凭证提交事件。

流程

签发监控凭证

你的后端使用 API 密钥和用户的 vendor_data 调用 POST /v3/events/sdk-token/。

从设备提交

应用携带 X-Monitoring-Token 请求头，向 POST /v1/events/（或 POST /v1/events/batch/）发送请求。

规则照常运行

事件会经过信息补充和汇总处理，并由与评估服务端提交事件时完全相同的规则进行评估。

签发凭证

签发凭证要求应用已开启事件接入。在其关闭期间，该 endpoint 会返回 403 及 {"code": "event_monitoring_disabled"}，而不会签发一个永远无法用于写入事件的凭证。

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

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

服务器端强制执行的约束

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

每次刷新最多发送 500 个事件，逐项结果与服务端批量 endpoint一致。推荐的默认刷新条件为：累计 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。

选择通道

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

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

入门

功能

参考

控制台

客户端事件采集 SDK - 事件提交

流程

签发凭证

提交

服务器端强制执行的约束

批量处理

背压时丢弃哪些事件

请求头兼容性

选择通道

后续步骤

事件接入

事件上的规则

​流程

​签发凭证

​提交

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

​批量处理

​背压时丢弃哪些事件

​请求头兼容性

​选择通道

​后续步骤

事件接入

事件上的规则

流程

签发凭证

提交

服务器端强制执行的约束

批量处理

背压时丢弃哪些事件

请求头兼容性

选择通道

后续步骤