SwAdNative

Ad Placement Four Essentials
Use case: native ad cards inside content feeds (mixed into list / grid feeds; slotKey e.g. home_feed)
Industry form: Native / In-feed ads (AdSDK format native)
Visual form: a card of cover image + title + description + advertiser + CTA, blending into the page style
Tracking events: same as banner — adImpression (once on entering the viewport via IntersectionObserver) / adClick; built-in zero-config, silent no-op when the tracker gate is off
Picking the wrong scenario = wrong ad_type / timing in tracking. See Ad Component Selection.

SwAdNative is the native feed ad slot component — a "text-card-type" self-rendering component of the ad foundation. It renders a native "image + title + description + advertiser + CTA" card that blends into a feed. It supports banner-list (single-column large-image cards) and grid (multi-column grid) layouts. Impression / click tracking is built in.

加载中...

Props

Name	Type	Required	Default	Description
`items`	`SwAdItem[]`	✓	—	Ad creative array (uses `image`/`title`/`description`/`advertiser`/`cta`)
`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`		`'16/9'`	Card main-image aspect ratio
`radius`	`number \| string`		`8`	Corner radius (number = px, string passed to SwImage as-is, e.g. `'1.125rem'`)
`showAdLabel`	`boolean`		`undefined`	"Ad" compliance badge; when not set it follows the global `swiftConfig.ad.showLabel` (default `true`), an explicit value always wins
`layout`	`'banner-list' \| 'grid'`		`'banner-list'`	Layout: single-column cards / multi-column grid
`gridColumns`	`number \| { mobile?, tablet?, desktop? }`		`2`	`grid` columns. Object form sets per-breakpoint tiers (<768 / 768-1023 / ≥1024), missing tiers fall back to the nearest one (same pattern as SwGallery `columns`)
`gridGap`	`number \| string`		`12`	Gap (number = px, string used as-is — can reference a token)

Events

Name	Payload	Description
`load`	—	Rendered
`empty`	—	`items` empty
`impression`	`items: SwAdItem[]`	Impression (auto tracking)
`click`	`item: SwAdItem`	A card clicked (auto tracking)
`error`	—	Render / load error

加载中...

<SwAdNative :items="feedAds" slot-key="feed_native" page-key="discover" ratio="16/9" :radius="8" show-ad-label />

<!-- Responsive columns: 1 on mobile / 2 on tablet / 3 on desktop -->
<SwAdNative :items="feedAds" slot-key="feed_native" layout="grid" :grid-columns="{ mobile: 1, tablet: 2, desktop: 3 }" />

<!-- gridGap / radius accept strings: tokens / rem -->
<SwAdNative :items="feedAds" slot-key="feed_native" layout="grid" grid-gap="1rem" radius="0.75rem" />

CSS variables

Layout is no longer inline style — everything lands as CSS variables, so business CSS can override the layout with plain rules, no !important needed:

Variable	Default	Description
`--sw-ad-native-gap`	`12px`	Card gap (maps to `gridGap`, applies to both banner-list and grid)
`--sw-ad-native-cols-mobile` / `--sw-ad-native-cols-tablet` / `--sw-ad-native-cols-desktop`	`2`	Grid column count per breakpoint (maps to `gridColumns`)

Caveats

Card fields: image (main image) / title / description / advertiser / cta (button text), driven by item data.
Tracking is built in and gated; see Ad & Tracking for full fields.