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，否則頻控記錄互相覆蓋。

相關