BeeX 活动展示位配置方案

一、方案目标

首页活动 Banner、活动弹窗、悬浮活动入口不再写死在 H5 页面里，而是通过统一活动运营位配置下发。

后端负责按国家、人群规则、档期、启用状态和优先级筛选配置；H5 负责按展示位渲染、处理频控、跳转和埋点。

二、一期范围

后续可复用扩展

三、下发链路

flowchart TD
  A["运营后台配置 campaign_placements"] --> B["前台批量查询 GET /api/v1/campaigns/placements"]
  B --> C{"后端过滤"}
  C --> D["国家 countryCode"]
  C --> E["人群 audienceRule"]
  C --> F["档期 startAt / endAt"]
  C --> G["状态 ACTIVE"]
  D --> H["按 placement 分组返回"]
  E --> H
  F --> H
  G --> H
  H --> I{"H5 本地频控"}
  I -->|通过| J["渲染 Banner / 弹窗 / 悬浮入口"]
  I -->|不通过| K["本次不展示"]
  J --> L["点击后按 action 跳转"]
  J --> M["曝光 / 点击 / 关闭埋点"]
      

四、核心数据模型

type CampaignPlacement = {
  id: string
  countryCode: string
  name: string
  placement: CampaignPlacementCode
  status: 'DRAFT' | 'ACTIVE' | 'DISABLED'
  priority: number
  startAt: string
  endAt?: string
  audienceRule?: CampaignAudienceRule
  content: CampaignPlacementContent
  action: CampaignPlacementAction
  frequencyRule?: CampaignFrequencyRule
}

展示位枚举

type CampaignPlacementCode =
  | 'HOME_BANNER'
  | 'HOME_POPUP'
  | 'HOME_FLOATING_ENTRY'
  | 'PRODUCT_DETAIL_CARD'
  | 'COUPON_ENTRY'
  | 'PROFILE_BANNER'
  | 'WITHDRAW_SUCCESS'

数据表建议

五、配置字段

六、人群、内容、动作和频控

type CampaignAudienceRule = {
  loginRequired?: boolean
  roles?: Array<'USER'>
  newUserOnly?: boolean
  minAppVersion?: string
  maxAppVersion?: string
}

type CampaignPlacementContent = {
  title?: string
  subtitle?: string
  description?: string
  imageUrl?: string
  iconUrl?: string
  buttonText?: string
  backgroundColor?: string
}

跳转动作

频控规则

type CampaignFrequencyRule = {
  mode: 'EVERY_TIME' | 'ONCE_PER_DAY' | 'ONCE_PER_CAMPAIGN'
  dismissTtlHours?: number
}

七、前台查询接口

GET /api/v1/campaigns/placements?countryCode=ID&placements=HOME_BANNER,HOME_POPUP,HOME_FLOATING_ENTRY&userId=usr_xxx&role=USER&environmentId=id-test

响应结构

type CampaignPlacementsResponse = {
  placements: Partial<Record<CampaignPlacementCode, CampaignPlacement[]>>
}

{
  "success": true,
  "message": "OK",
  "data": {
    "placements": {
      "HOME_BANNER": [],
      "HOME_POPUP": [],
      "HOME_FLOATING_ENTRY": []
    }
  }
}

八、管理后台接口

创建和更新请求

type AdminCampaignPlacementRequest = {
  countryCode: CountryCode
  name: string
  placement: CampaignPlacementCode
  status?: 'DRAFT' | 'ACTIVE' | 'DISABLED'
  priority: number
  startAt: string
  endAt?: string
  audienceRule?: CampaignAudienceRule
  content: CampaignPlacementContent
  action: CampaignPlacementAction
  frequencyRule?: CampaignFrequencyRule
}

九、H5 接入方案

H5 增加统一组合函数 useCampaignPlacements()，集中处理拉取、频控、展示、跳转和埋点。

十、事件上报

活动曝光、点击、关闭、领券转化优先通过埋点体系上报。只有后端需要实时消费活动事件时，才启用业务接口。

POST /api/v1/campaigns/events

{
  "campaignPlacementId": "cpl_home_banner_001",
  "campaignId": "cmp_xxx",
  "placement": "HOME_BANNER",
  "eventType": "IMPRESSION",
  "userId": "usr_xxx",
  "countryCode": "ID",
  "platform": "H5",
  "extra": {
    "route": "/"
  }
}

十一、当前状态与边界

十二、维护与发布

1. 在 id-test 创建草稿并使用真接口预览，不把 mock 数据发布给运营。
2. 素材上传后确认 CDN 可访问，检查目标页面、时间窗和 USER 命中结果。
3. 测试通过后由管理后台把同一配置转入生产环境，再执行灰度和正式发布。
4. 发布后验证供数、曝光和点击；回滚时停用配置，不直接改历史记录。