useAdFrequency()

useAdFrequency 是广告展示频率控制 composable，通用于任何需频控的广告位（如 SwAdPopup 进站弹窗）。不绑"开屏"语义。决策记录走 framework 加密缓存 util（useSession / useLocal 自动拼 cachePrefix + AES 加密，不裸用 storage）。

参数

useAdFrequency(key, strategy)：

名称类型必填说明
keystring✓频控记录的唯一键（如 'home-popup'）。内部存为 ad_seen_<key>，便于 devtools 辨识
strategyAdFrequencyStrategy✓频率策略，见下表

AdFrequencyStrategy（'session' \| 'always' \| PeriodSpec）

取值含义存储
'session'会话内展示一次，关标签页重置sessionStorage（加密）
number > 0N 天内不再展示（N 可为小数，如 0.5 = 12 小时）localStorage（加密，存时间戳）
0 / 负数每次都展示（调试 / 不限频）不读写

返回值

名称类型说明
shouldShow() => boolean当前是否该展示。SSR 返回 false —— 频控是 client-only 决策
markShown() => void标记已展示（写入加密缓存）

使用示例

// 示例 1：进站弹窗，会话内只弹一次
const { shouldShow, markShown } = useAdFrequency('home-popup', 'session')
onMounted(() => {
  if (shouldShow()) {
    openPopup()
    markShown()
  }
})

// 示例 2：促销弹窗，3 天弹一次
const { shouldShow, markShown } = useAdFrequency('promo-2026', 3)
onMounted(() => {
  if (shouldShow()) {
    openPromo()
    markShown()
  }
})

// 示例 3：调试期不限频（每次都弹）
const { shouldShow } = useAdFrequency('debug-ad', 0)

工作原理

  • 决策逻辑抽成纯函数 shouldShowByStrategy(strategy, stored, now)（不碰 storage / Date，便于单测）：
    • number <= 0 → 始终 true（每次）
    • 'session' → 无标记才 true（会话内未展示过）
    • number > 0 → 无标记、或 now - 上次展示时间 >= N 天 才 true
  • shouldShow() 在 SSR（!IS_CLIENT）直接返回 false，避免服务端误判 + hydration 不一致。

注意事项

  • 先 shouldShow() 判断，再 markShown() —— markShown 不会自动在展示时调用，需业务在真正展示后显式标记。
  • key 要全站唯一，不同广告位用不同 key，否则频控记录互相覆盖。

相关