# App 埋点 Flutter 对接

## 地址

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

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

```http
Authorization: Bearer <access_token>
```

未登录时必须传 `device_id` 或 Header：

```http
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`，客户端不要传这些字段。

示例：

```json
{
  "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
    }
  ]
}
```

## 返回值

```json
{
  "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

无。