guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# POST /api/v1/analytics/events — 批量上报埋点事件
|
||
|
||
> 所属:Analytics 组（前缀 `/api/v1/analytics`） | 鉴权:无（不强制登录，未登录态也要采集行为） | [← 返回 API 索引](../README.md)
|
||
|
||
批量接收新手引导（及后续）埋点，append 落 `analytics_event` 表。`user_id` 由客户端在 body 可选带上，不靠 Bearer。服务端补 `client_ip`（X-Forwarded-For）与 `server_at`（接收时间）。
|
||
|
||
## 入参
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `device_id` | string | ✅（≤64） | 设备 ID |
|
||
| `user_id` | int \| null | ❌ | 登录用户 ID（未登录可空） |
|
||
| `sent_at` | int \| null | ❌ | 批次发送时间（epoch ms） |
|
||
| `oem` | string \| null | ❌ | 厂商（如 `Xiaomi`） |
|
||
| `os` | string \| null | ❌ | 操作系统（如 `Android 14`） |
|
||
| `model` | string \| null | ❌ | 机型（如 `24115RA8EC`） |
|
||
| `app_ver` | string \| null | ❌ | App 版本 |
|
||
| `channel` | string \| null | ❌ | 渠道 |
|
||
| `events` | list[object] | ✅（1-200 条） | 事件数组 |
|
||
| `events[].event` | string | ✅（≤64） | 事件名（如 `onboarding_start`） |
|
||
| `events[].client_ts` | int | ✅ | 端事件发生时间（epoch ms） |
|
||
| `events[].session_id` | string \| null | ❌ | 会话 ID |
|
||
| `events[].page` | string \| null | ❌ | 页面标识 |
|
||
| `events[].network` | string \| null | ❌ | 网络类型（如 `wifi`） |
|
||
| `events[].props` | dict | ❌ | 事件属性（key-value） |
|
||
|
||
Mock 入参:
|
||
```json
|
||
{
|
||
"device_id": "android_abc123def456",
|
||
"user_id": 42,
|
||
"sent_at": 1719993700000,
|
||
"oem": "Xiaomi",
|
||
"os": "Android 14",
|
||
"model": "24115RA8EC",
|
||
"app_ver": "0.1.5",
|
||
"channel": "official",
|
||
"events": [
|
||
{
|
||
"event": "onboarding_start",
|
||
"client_ts": 1719993600000,
|
||
"session_id": "sess_a1b2c3",
|
||
"page": "onboarding",
|
||
"network": "wifi",
|
||
"props": {"step": "1", "source": "fresh_install"}
|
||
},
|
||
{
|
||
"event": "onboarding_step_complete",
|
||
"client_ts": 1719993615000,
|
||
"session_id": "sess_a1b2c3",
|
||
"page": "onboarding",
|
||
"network": "wifi",
|
||
"props": {"step": "1", "duration_ms": "15000"}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 出参
|
||
|
||
响应 `200`:`AnalyticsIngestOut`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `ok` | bool | 固定 `true` |
|
||
| `received` | int | 成功写入的条数 |
|
||
|
||
Mock 出参:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"received": 2
|
||
}
|
||
```
|
||
|
||
## 错误码
|
||
- `422` `events` 为空或超过 200 条 / 字段类型不符
|
||
|
||
## 说明
|
||
- `user_id` 不靠 JWT：未登录态也要采集行为（新手引导可能在登录前）
|
||
- 每批最多 200 条，建议客户端攒到一定量再批量上报
|
||
- `client_ts` 是端侧时间（客户端时钟），`server_at` 由服务端补（可靠时间轴）
|