SwAdPopup

Ad Placement Four Essentials

• Use case: fullscreen popups triggered by business actions — button click / exit-intent / once every N swipes in a short-video feed (SwVideoFeed @change counter → popupRef.open()); slotKey e.g. feed_popup
• Industry form: Interstitial / Vignette (AdSDK format popup)
• Visual form: fullscreen overlay + single images popped one by one (sequential) or story-stream carousel (carousel) + dismissible countdown
• Tracking events: adImpression (reported as soon as the popup layer shows, ad_type=popup) / adClick; built-in zero-config, silent no-op when the gate is off

⚠️ For the auto-popup-on-entry splash, use SwAdSplash, not this component (the trigger=onload mode has been removed). Picking the wrong scenario = wrong ad_type / timing in tracking. See Ad Component Selection.

SwAdPopup is the business-triggered fullscreen popup ad slot component — the business holds a ref and calls open() / close(); it does not pop automatically. It shares the same popup core as SwAdSplash (auto-popup on entry); the only differences are trigger method (manual vs auto-on-entry) + frequency default (0 vs session) + ad_type (popup vs splash). Multiple creatives can be shown sequentially or as a story-stream carousel. Impression / click tracking is built in.

Copy + CTA overlay (opt-in): when an item carries any of title / description / cta / advertiser, a "headline + sub-copy + CTA button" overlay renders over the creative image (like a real ad); pass only image to keep it image-only. The CTA is a button-styled <span> (the whole ad is already a link; clicks go to link).

Props

Events

Exposed methods (ref)

Story-stream carousel + optional frequency capping

mode="carousel" shows multiple creatives as a story stream, with a closableAfter countdown and autoplayDelay switching interval. frequency defaults to 0 (no capping — every open() pops); to layer on a cap (e.g. a feed's "every N swipes but at most one round per session") pass frequency="session":

<!-- Manual trigger -->
<SwAdPopup ref="popupRef" :items="ads" slot-key="promo" />
<SwButton @click="popupRef?.open()">View campaign</SwButton>

<!-- Once every 5 swipes in a short-video feed, at most one round per session -->
<SwAdPopup ref="feedPopup" :items="ads" slot-key="feed_popup" frequency="session" />
<!-- SwVideoFeed @change: if (++count % 5 === 0) feedPopup.value?.open() -->

<!-- Non-modal (overlay=false, background not locked) + carousel stops at the last slide (loop=false) +
     frequency-key: explicit capping storage key (defaults to slot-key; change the key on release to reset capping) -->
<SwAdPopup :items="ads" slot-key="promo" mode="carousel" :overlay="false" :loop="false" frequency-key="promo-2026q3" />

Style Tokens

Knobs of the shared AdPopupBase kernel (SwAdSplash uses the exact same set; the fallback is the default):

The title / description / CTA overlay on the creative is rendered by the internal AdOverlay; its knobs are --sw-ad-overlay-* (shared by three ad components) — see SwAdPreroll · Creative Overlay Tokens.

Caveats

• The business owns trigger timing — the component doesn't pop automatically; the business holds a ref and calls open() at the right moment (click / exit intent / feed swipe counter, etc.).
• frequency defaults to 'always' (no capping); pass 'session' / N days to layer on a capping cap (useAdFrequency; on a miss open() silently doesn't pop).
• When closableAfter > 0, closing is blocked during the countdown (mis-touch guard); the close button appears when it ends.
• Tracking is built in (ad_type=popup) and behind the tracker's double gate.