109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# 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
|
||
|
||
无。
|