廣告元件選型

framework 的 SwAd* 廣告元件族按廣告位場景（placement）組織，與業界主流 SDK（AdMob / MAX 系的 BannerAd / InterstitialAd / NativeAd）同一套詞表。本文是選型的唯一決策入口：先定場景，再選元件。

為什麼按場景選，不按外觀選

廣告元件內建了兩件業務看不見但資料側極度在意的東西：

埋點 ad_type：每個元件按自身場景上報固定的 ad_type（banner / mrec / popup / preroll / floating…）。拿 SwAdBanner 去做彈窗，上報的 ad_type=banner 會讓資料側的彈窗報表永遠是 0。
曝光時機語義：多數元件用 IntersectionObserver「進視口一次」上報曝光；但 SwAdPopup 是「彈層展示即報」、SwAdPreroll 是「掛載即報」（貼片層由播放器門控、掛載=必然可見）。把 SwAdPreroll 放進常規版面，會在使用者根本看不見時虛報曝光。

反面案例（真實業務考古，匿名化）：某站為列表頁自造了宮格廣告元件——點擊埋點寫了、曝光埋點整段缺失，上線後資料側只有 click 沒有 impression，CTR 報表全部失真；另一站的應用推廣卡元件埋點程式碼整段空置（寫了註解沒寫實作）。自造廣告元件的埋點幾乎必然爛尾，這正是埋點下沉到 framework 元件的原因。

場景選型表

我要做的廣告位	用	業界對應詞	曝光時機	典型資料來源
進站 / 開屏自動彈（帶頻控）	SwAdSplash（`mode=sequential/carousel`）	App-Open / Splash	彈層展示即報（`ad_type=splash`）	`system/info.layers`
業務觸發全螢幕彈窗（點擊 / feed 每滑 N 條）	SwAdPopup（`ref.open()`）	Interstitial / Vignette	彈層展示即報（`ad_type=popup`）	業務自定
頁面橫幅（頂 / 中 / 頁腳 / 播放器周邊）	SwAdBanner	Banner / Leaderboard	IO 進視口一次	`ads.home_banner` 等
正文側欄 / 播放頁矩形位	SwAdMrec	MREC（IAB 300×250）	IO 進視口一次	`ads.*_mrec`
應用推薦宮格 / 橫排 / 列表宮格	SwAdIcon	Icon ads	IO 進視口一次	`ads.app_info_*`
文字鏈（導航條下 / 頂部）	SwAdText	Text link	IO 進視口一次	`ads.top_links`
公告位橫向滾動	SwAdMarquee	Marquee	IO 進視口一次	`ads.*_marquee`
內容流內原生卡	SwAdNative	Native / In-feed	IO 進視口一次	`ads.*_feed`
左右側固定懸浮（窄螢幕隱藏）	SwAdFloating	Floating / Anchor	可見即報	`ads.app_float_right`
影片前貼片（播放器 `#preroll-ad` 插槽）	SwAdPreroll	IAB in-stream pre-roll	掛載即報	詳情介面 `play_ads` / `ads.app_info_player_preroll`
影片暫停廣告（播放器 `#pause-ad` 插槽）	SwAdPause	Pause Ad / Pause Screen Ad	展示即報（暫停 gating 通過彈，可關閉）	`ads.app_info_player_pause`
合規「廣告」角標	SwAdLabel	Ad badge	不上報	—

預留場景（暫無元件，名字已佔住、將來不得用別名實作）：SwAdInterstitial（插屏）。需要這些場景時提 framework issue，不要業務自造。

「廣告位四要素」怎麼讀

每個 SwAd* 元件的 JSDoc 檔案頭和 docs 元件頁頭部都有同款四要素塊：

使用場景：這個元件該出現在頁面的什麼位置、什麼時機——對不上就換元件
業界形態：IAB / 主流 SDK 的對應詞（方便與資料側、營運對齊口徑）
表現形態：渲染出來長什麼樣（單圖 / 輪播 / 宮格 / 彈層…）
打點事件：自動上報哪些事件、曝光時機是哪種語義

寫程式碼落到具體元件前，先核四要素的「使用場景」行；UI 長得像不代表場景對。

資料來源協定速查

// ① system/info.layers —— 進站開屏佇列（SwAdSplash）
//    每層 { type: 'adv'|'app'|'notice', data: ... }

// ② system/info.ads.* —— 按槽位 key 下發的各廣告位
//    如 ads.home_banner / ads.top_links / ads.app_float_right

// ③ 詳情介面 play_ads —— 影片前貼片（{ id, name, content, link }）
//    一行歸一：playAdsToSwAdItems(r.play_ads) → SwAdItem[]

元件統一只認 SwAdItem；將來接入 AdSDK（getAd 資料面）會提供同樣歸一到 SwAdItem 的 adapter，元件無感切換資料來源。

埋點鏈路與 gate

曝光 / 點擊埋點元件內建零組態，走 useAdTrack → WebSDK（adImpression / adClick）
上報受 swift.config.json 的 tracker.enabled + system/info.tracker 雙重 gate——缺任一靜默 no-op，元件照寫、不發請求，開發期不會誤報髒資料
業務額外統計用元件的 @impression / @click 事件（自動埋點已發，事件供疊加消費）
自有打點 SDK 場景：原始事件全透傳 + useExposure 公開曝光時機，可完全繞開內建埋點