廣告元件與埋點

選型先行：按場景選 SwAd* 元件（不按外觀）的決策入口見 廣告元件選型；每個元件頁頭部的「廣告位四要素」是落地前最後一道核對線。

底座在別處：通用打點能力（自動 pageView / useTracker 自訂事件 / :track 內容埋點 / useExposure）見 打點底座 —— 本頁只講廣告位這個消費方。

framework 提供一套自渲染廣告元件 SwAd*，埋點構建在 打點底座 之上。業務做廣告位零程式碼接入、自動埋點 —— 不必自己寫廣告元件、不必手搓 IntersectionObserver。

廣告元件 SwAd*

按廣告位形態選元件（命名 / ad_type 對齊集團 AdSDK 詞彙，便於將來遷移）：

元件形態典型場景
SwAdBanner橫幅（單張 / 多張輪播）內容流橫幅、側欄
SwAdMrec中等矩形（300×250）資訊流插入
SwAdIcon圖示網格App 推薦位
SwAdText文字連結文字推廣
SwAdMarquee跑馬燈通知滾動
SwAdNative原生資訊流卡片資訊流原生廣告
SwAdSplash進站開屏彈窗 / 故事流（ad_type=splash）進站自動彈、開屏
SwAdPopup業務觸發彈窗 / 故事流（ad_type=popup）點擊 / 退出挽留 / feed 每滑 N 條
SwAdFloating側邊懸浮PC 側邊
SwAdPreroll影片前貼片播放器 #preroll-ad 插槽
SwAdPause影片暫停廣告（ad_type=pause）播放器 #pause-ad 插槽（暫停時彈、可關閉）

用法（自渲染 + 自動埋點，零程式碼）：

<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 —— 詳見 打點底座 · 接入與設定。