SwAdSplash

Ad Placement Four Essentials
Use case: auto-popup on entry / first screen splash ad (on the web, a splash ≈ a fullscreen entry popup; slotKey e.g. splash). Data usually comes from the image ad layers in system/info.layers
Industry form: App-Open / Splash (AdSDK format splash)
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=splash) / adClick; built-in zero-config, silent no-op when the gate is off
⚠️ For fullscreen popups triggered by business actions (button click / every N swipes in a feed), use SwAdPopup, not this component. Picking the wrong scenario = wrong ad_type / timing in tracking. See Ad Component Selection.

SwAdSplash is the auto-popup-on-entry splash ad slot component — onMounted, it pops once after a delay, capped by useAdFrequency (default 'session', once per session). It shares the same popup core as SwAdPopup (triggered by the business via ref.open()); the only differences are auto trigger + frequency default 'session' + ad_type=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

Name	Type	Required	Default	Description
`items`	`SwAdItem[]`	✓	—	Ad creative array
`slotKey`	`string`	✓	—	Ad slot key → `ad_slot_key`
`slotName`	`string`		`undefined`	Ad slot name → `ad_slot_name`
`pageKey`	`string`		`undefined`	Page key → `page_key`
`pageName`	`string`		`undefined`	Page name → `page_name`
`ratio`	`string`		`'3/4'`	Popup creative aspect ratio
`overlay`	`boolean`		`true`	Show the overlay
`mode`	`'sequential' \| 'carousel'`		`'sequential'`	Multi-creative: one-by-one / story-stream carousel
`delay`	`number`		`1000`	Entry delay before popping (ms)
`frequency`	`AdFrequencyStrategy`		`'session'`	Frequency strategy (`'session'` per session / `'always'` every time / `'Nm'`·`'Nh'`·`'Nd'` once every N minutes·hours·days)
`frequencyKey`	`string`		`undefined`	Frequency storage key (defaults to `slotKey`)
`showAdLabel`	`boolean`		`undefined`	"Ad" compliance badge; when not set it follows the global `swiftConfig.ad.showLabel` (default `true`), an explicit value always wins
`autoplayDelay`	`number`		`3000`	`carousel` interval (ms)
`closableAfter`	`number`		`0`	Closable only after N milliseconds (mis-close guard; 0 = closable immediately)
`loop`	`boolean`		`true`	Whether `carousel` loops

Events

Name	Payload	Description
`open`	—	Popup opened
`close`	—	Popup closed
`empty`	—	`items` empty (no popup)
`impression`	`items: SwAdItem[]`	Impression (auto tracking)
`click`	`item: SwAdItem`	Creative clicked (auto tracking)
`error`	—	Render / load error

Exposed methods (`ref`)

Method	Description
`close()`	Close the popup manually (the countdown / ✕ are handled internally, usually no need to call)

Entry frequency capping + story stream

The on-entry auto-popup is capped by frequency ('session' once per session / '7d' once every 7 days / 'always' every time); mode="carousel" shows multiple creatives as a story stream, with a closableAfter countdown lock and autoplayDelay switching interval:

<!-- Pop once per session on entry -->
<SwAdSplash :items="splashAds" slot-key="splash" />

<!-- Story-stream carousel + once every 7 days + 4s close lock; auto-advance every 3s,
     stop at the last slide (loop=false); ratio="9/16" for full-screen portrait creatives -->
<SwAdSplash
  :items="splashAds"
  slot-key="splash"
  mode="carousel"
  ratio="9/16"
  :frequency="7"
  :closable-after="4000"
  :autoplay-delay="3000"
  :loop="false"
/>

Styling Tokens

Popup chrome colors are themeable via --sw-ad-popup-* tokens (fallbacks are the default media-context black/white values; SwAdSplash shares the same kernel tokens):

--sw-ad-popup-overlay-bg (black 60%) · -topbar-gradient · -pill-bg (white 12%) · -pill-color (white) · -seq-border (white 60%) · -seq-color (white 90%) · -bar-track (white 25%) · -bar-fill (var(--primary), accepts a brand gradient) · -nav-bg (black 35%) · -nav-color (white)

This component shares the AdPopupBase kernel with SwAdPopup — the --sw-ad-popup-* knobs apply here too; see SwAdPopup · Style Tokens. For the title / CTA overlay knobs --sw-ad-overlay-*, see SwAdPreroll · Creative Overlay Tokens.

Caveats

Auto-popup on entry — onMounted it pops after delay; no need for the business to call open(); on a frequency miss it silently doesn't pop.
Capping uses useAdFrequency — automatic capping per the frequency strategy ('session' uses sessionStorage, N days uses localStorage); no manual checks needed.
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=splash) and behind the tracker's double gate.