广告组件与埋点

选型先行：按场景选 SwAd* 组件（不按外观）的决策入口见 广告组件选型；每个组件页头部的「广告位四要素」是落地前最后一道核对线。

底座在别处：通用打点能力（自动 pageView / useTracker 自定义事件 / :track 内容埋点 / useExposure）见 打点底座 —— 本页只讲广告位这个消费方。

framework 提供一套自渲染广告组件 SwAd*，埋点构建在 打点底座 之上。业务做广告位零代码接入、自动埋点 —— 不必自己写广告组件、不必手搓 IntersectionObserver。

广告组件 SwAd*

按广告位形态选组件（命名 / ad_type 对齐集团 AdSDK 词汇，便于将来迁移）：

用法（自渲染 + 自动埋点，零代码）：

<SwAdBanner :items="ads" slot-key="home_banner" />
<SwAdSplash :items="splashAds" slot-key="splash" mode="carousel" :closable-after="4000" />

items 是 SwAdItem[]（{ id, image, link, name, adType? }），组件自渲染图片 + 链接，曝光 / 点击自动埋点。各组件 props（ratio / radius / showAdLabel / mode / loop 等）见组件 JSDoc。

合规角标 showAdLabel

全部 SwAd* 默认带「广告」合规角标：组件不传 showAdLabel 时跟随全局 swiftConfig.ad.showLabel（默认 true）。默认全员带标是合规安全侧的取舍——忘了关多一个角标只是难看，忘了开则广告无标识、是合规风险；需要关的显式关：

• 素材图内已画好广告标识的站点，在 nuxt.config.ts 全局关闭：swiftConfig: { ad: { showLabel: false } }
• 个别位需要不同行为时，组件级 show-ad-label 显式传值始终优先（全局关后可单独开，反之亦然）

配置详见 Module Options · ad；自建非标广告位需要角标时直接用 SwAdLabel。

广告埋点（自动）

SwAd* 内置 useAdTrack：元素进视口一次 → adImpression、点击 → adClick、点关闭钮 ✕ → adClose（payload 带 close_reason: 'close'，SwAdSplash / SwAdPopup / SwAdPause 已接线——关闭率是「广告打扰度」核心信号），埋点字段（位级 slotKey/slotName/page + 创意级 ad_id/creative_id/ad_type）自动组装，零代码。组件同时把 @impression / @click / @close 事件外抛，业务有别的用处可监听。贴片「跳过」按钮归业务 slot 渲染，业务在 skip handler 里自调 useAdTrack(...).reportClose(items, 'skip') 即可（倒计时自然结束不报）。

广告埋点字段不要在业务侧手拼 payload —— 自建非标广告位需要埋点时也走 useAdTrack。

配置与降级

广告埋点与底座共用同一套双重 gate（tracker.enabled + system/info.tracker），任一缺失静默 no-op —— 详见 打点底座 · 接入与配置。