hyapp-server/docs/flutter对接/弹窗配置Flutter对接.md

弹窗配置 Flutter 对接

地址

GET /api/v1/app/popups

公开接口，不需要登录。返回后台 APP配置 -> 弹窗配置 中当前有效的弹窗列表。

参数

参数	位置	必填	说明
X-App-Code	Header	否	App 编码，默认 lalu。
X-App-Package	Header	否	包名或 Bundle ID，用于服务端解析 App。

示例：

GET /api/v1/app/popups
X-App-Code: lalu

返回值

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

无。