73 lines
2.1 KiB
Markdown
73 lines
2.1 KiB
Markdown
# 弹窗配置 Flutter 对接
|
||
|
||
## 地址
|
||
|
||
`GET /api/v1/app/popups`
|
||
|
||
公开接口，不需要登录。返回后台 `APP配置 -> 弹窗配置` 中当前有效的弹窗列表。
|
||
|
||
## 参数
|
||
|
||
| 参数 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `X-App-Code` | Header | 否 | App 编码，默认 `lalu`。 |
|
||
| `X-App-Package` | Header | 否 | 包名或 Bundle ID，用于服务端解析 App。 |
|
||
|
||
示例：
|
||
|
||
```http
|
||
GET /api/v1/app/popups
|
||
X-App-Code: lalu
|
||
```
|
||
|
||
## 返回值
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_abc",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 21,
|
||
"code": "new-user-popup",
|
||
"name": "新人活动",
|
||
"image_url": "https://cdn.example.com/popup.png",
|
||
"jump_type": "h5",
|
||
"jump_url": "https://h5.example.com/new-user",
|
||
"display_period_days": 1,
|
||
"sort_order": 1,
|
||
"starts_at_ms": 1700000000000,
|
||
"ends_at_ms": 1800000000000,
|
||
"updated_at_ms": 1700000004000
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `items` | 当前可展示的弹窗配置列表，已按 `sort_order ASC, id DESC` 排序。 |
|
||
| `code` | 弹窗编码，同一个 App 下唯一，用于 Flutter 本地频控和埋点识别。 |
|
||
| `name` | 弹窗名字。 |
|
||
| `image_url` | 弹窗图片地址，可能为空。 |
|
||
| `jump_type` | `h5` 或 `app`。 |
|
||
| `jump_url` | `jump_type=h5` 时是 H5 链接；`jump_type=app` 时由 Flutter 解释。 |
|
||
| `display_period_days` | 展示周期。`0` 表示每次打开 App 都展示；`1` 表示 1 天展示一次；`2`、`3`、`4` 同理。 |
|
||
| `starts_at_ms` / `ends_at_ms` | 弹窗生效时间。`0` 表示不限。 |
|
||
|
||
Flutter 处理规则：
|
||
|
||
1. 调接口后按 `items` 顺序取第一个满足本地频控的弹窗。
|
||
2. 用 `popup_last_show:{code}:{updated_at_ms}` 记录本地最后展示时间。
|
||
3. `display_period_days=0` 不读本地间隔，每次打开都可以展示。
|
||
4. `display_period_days>0` 时，距离上次展示满对应天数后再展示。
|
||
5. 用户点击弹窗时，`jump_type=h5` 打开 H5；`jump_type=app` 走 App 内路由。
|
||
|
||
## 相关 IM
|
||
|
||
无。
|