# 弹窗配置 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

无。