shaguabijia-app-server/docs/api/other/analytics-events.md

POST /api/v1/analytics/events — 批量上报埋点事件

所属:Analytics 组（前缀 /api/v1/analytics） | 鉴权:无（不强制登录，未登录态也要采集行为） | ← 返回 API 索引

批量接收新手引导（及后续）埋点，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 入参:

{
  "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 出参:

{
  "ok": true,
  "received": 2
}

错误码

• 422 events 为空或超过 200 条 / 字段类型不符

说明

• user_id 不靠 JWT：未登录态也要采集行为（新手引导可能在登录前）
• 每批最多 200 条，建议客户端攒到一定量再批量上报
• client_ts 是端侧时间（客户端时钟），server_at 由服务端补（可靠时间轴）