hyapp-server/docs/flutter对接/App埋点Flutter对接.md

App 埋点 Flutter 对接

地址

POST /api/v1/app/events
Content-Type: application/json

可登录也可未登录调用。已登录时建议带：

Authorization: Bearer <access_token>

未登录时必须传 device_id 或 Header：

X-Device-ID: <device_id>

参数

Body：

字段	类型	必填	说明
events	array	是	埋点列表，单次最多 50 条。

events[]：

字段	类型	必填	说明
event_id	string	是	客户端生成的唯一事件 ID。同一事件重试必须复用同一个值。
event_name	string	是	事件名，例如 banner_view、banner_click、page_open。
event_type	string	否	事件类型，例如 view、click、submit。
screen	string	否	页面或模块，例如 home、room、me。
target_type	string	否	目标类型，例如 banner、button、room。
target_id	string	否	目标 ID，例如 banner ID、房间 ID。
device_id	string	未登录必填	设备 ID。也可以放到 X-Device-ID。
session_id	string	否	客户端本地会话 ID。登录态下服务端优先使用 token 里的 session。
platform	string	否	android 或 ios。不传时读取 X-App-Platform / X-Platform。
app_version	string	否	App 版本。不传时读取 X-App-Version / X-Client-Version。
language	string	否	语言。不传时读取 X-App-Language / X-Language / Accept-Language。
timezone	string	否	客户端时区，只做属性记录，不参与业务切日。
duration_ms	int64	否	客户端记录的耗时毫秒。
success	bool	否	动作是否成功。
error_code	string	否	失败时的客户端错误码。
properties	object	否	扩展属性，最大 4KB。
occurred_at_ms	int64	否	事件发生时间，UTC epoch milliseconds。不传时使用服务端接收时间。

服务端会自己识别 app_code、user_id、country_id、region_id，客户端不要传这些字段。

示例：

{
  "events": [
    {
      "event_id": "evt_20260703_100001_banner_17_view",
      "event_name": "banner_view",
      "event_type": "view",
      "screen": "home",
      "target_type": "banner",
      "target_id": "17",
      "device_id": "device_xxx",
      "platform": "android",
      "app_version": "1.2.3",
      "language": "en-US",
      "timezone": "Asia/Shanghai",
      "success": true,
      "properties": {
        "position": "top"
      },
      "occurred_at_ms": 1778000005000
    }
  ]
}

返回值

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {
    "accepted": true,
    "received": 1,
    "stored": 1,
    "duplicated": 0,
    "server_time_ms": 1778000005000
  }
}

字段	说明
data.accepted	是否接受本次上报。
data.received	本次收到的事件数。
data.stored	本次新写入的事件数。
data.duplicated	已存在的事件数。通常是重试导致的重复 event_id。
data.server_time_ms	服务端时间，UTC epoch milliseconds。

相关 IM

无。