POST公开接口
批量上报事件
客户端批量上报行为事件。**事件名无需预先在服务端登记**：服务端第一次收到某个 事件名时自动创建对应的事件定义。 每条事件带一个客户端生成的 `event_id` 作为幂等键，离线队列重试补发时服务端靠它 去重，同一个 `event_id` 只会入库一次。`occurred_at` 是客户端声明的发生时间，落在 可信窗口（默认往前 7 天、往后 5 分钟）之外时回退到服务端接收时间。 返回 202 而非 201：接受请求与实际落库不是同一件事。命中退出信号 （`x-verhub-do-not-track: 1`）或项目关闭了事件采集时，本接口照常返回 202， 但不入库、不计数、不解析地理位置，此时 `suppressed` 为 true。 服务端另行记录调用方 IP、User-Agent、平台与解析出的地区。IP 默认以匿名化形式 存储（IPv4 截末段、IPv6 截末 80 位），由 VERHUB_EVENT_IP_STORAGE 控制； 归属地解析在匿名化之前用完整地址完成，精度不受影响。
URL
/api/v1/public/{projectKey}/events鉴权方式
无需鉴权
请求参数
Path 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| projectKey | string | 是 | 项目主键 project_key（大小写不敏感） |
Header 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| x-verhub-platform | windows | linux | macos | ios | android | web | others | 否 | 客户端平台声明，仅用于请求统计，不影响接口返回内容。 识别优先级：本请求头 > query 参数 `platform` > 请求体 `platform` 字段 > User-Agent 推断。 取值大小写不敏感，无法识别时统计为 OTHERS。 具体系统版本请用 `x-verhub-platform-version` 单独提交；若把版本混在本字段里 （如 `Windows 11`、`ubuntu 24.04`），服务端会拆开，平台与版本分别入库。 建议 SDK 显式声明本请求头：服务端调用的 User-Agent 往往不可靠。 |
| x-verhub-platform-version | string | 否 | 客户端系统版本明细，仅用于请求统计，不影响接口返回内容。 自由文本，如 `11`、`ubuntu 24.04`、`26`；超过 32 字符视为无效直接丢弃。 识别优先级：本请求头 > query 参数 `platform_version` > 请求体 `platform_version` 字段 > 从 `platform` 中拆出的版本 > User-Agent 推断。 |
| x-verhub-do-not-track | string | 否 | 最终用户的退出信号。取 `1` / `true` / `yes` 之一即视为退出，此时事件采集端点 照常返回 202，但不入库、不计数、也不解析地理位置（解析本身就是一次对外的 数据传输，而用户已经表示不希望被采集）。 其余取值、空值与缺失都视为未退出：把无法解析的值当成退出，会让一个写错的 代理头静默关掉整个实例的采集。 本头是给**直接对接 HTTP 的接入方**用的。用 SDK 的场景不需要它：SDK 在 `optOut()` 之后根本不发请求，比发一个会被丢弃的请求更彻底，也不会在接口 调用量统计里留下痕迹。 |
请求体
{
"distinct_id": "9f1c2a7e-5b40-4a1d-9d3f-2c8e6b4a1f07",
"session_id": "string",
"events": [
{
"event_id": "3f7a1c9e-2d84-4f60-b1a2-7c5e9d0b4a63",
"name": "checkout_clicked",
"occurred_at": 1760000000,
"properties": {
"plan": "pro",
"amount": 199
}
}
],
"platform": "string",
"platform_version": "string"
}响应示例
202 响应
{
"accepted": 3,
"skipped": 0,
"suppressed": false
}POST
