useAdFrequency()

useAdFrequency is the ad display frequency-control composable, generic for any frequency-capped ad slot (e.g. the SwAdPopup entry popup). It isn't tied to "splash" semantics. Decision records go through the framework's encrypted cache utils (useSession / useLocal auto-prefix cachePrefix + AES-encrypt; no raw storage).

Parameters

useAdFrequency(key, strategy):

AdFrequencyStrategy ('session' \| 'always' \| PeriodSpec)

Return Value

Usage Examples

// Example 1: entry popup, once per session
const { shouldShow, markShown } = useAdFrequency('home-popup', 'session')
onMounted(() => {
  if (shouldShow()) {
    openPopup()
    markShown()
  }
})

// Example 2: promo popup, once every 3 days
const { shouldShow, markShown } = useAdFrequency('promo-2026', 3)
onMounted(() => {
  if (shouldShow()) {
    openPromo()
    markShown()
  }
})

// Example 3: uncapped during debugging (show every time)
const { shouldShow } = useAdFrequency('debug-ad', 0)

How It Works

• The decision logic is extracted into the pure function shouldShowByStrategy(strategy, stored, now) (touches no storage / Date, for easy unit testing):
  • number <= 0 → always true (every time)
  • 'session' → true only when there's no mark (not shown this session)
  • number > 0 → true when there's no mark, or now - lastShown >= N days
• shouldShow() returns false under SSR (!IS_CLIENT) to avoid server-side misjudgment + hydration mismatch.

Caveats

• Check shouldShow() first, then markShown() — markShown isn't called automatically on display; the business must mark explicitly after actually showing.
• Keep key globally unique; use distinct keys for distinct ad slots, otherwise frequency records overwrite each other.

Related

• SwAdPopup — popup ad component, often paired with this composable for entry frequency capping
• Ad & Tracking