打點底座

framework 把集團統一上報 WebSDK 封裝為打點底座：普通頁面流量統計（自動 pageView）、自訂事件（useTracker）、通用內容埋點（:track / useExposure）開箱即用。廣告埋點是底座之上的一個消費方，不是底座本身。

接入與設定

上報受雙重 gate：

swift.config.json 的 tracker.enabled（總開關，對應 swiftConfig.tracker）
system/info.tracker（後端下发的 appId / encryptedConfig）

任一缺失 → 静默 no-op（dev warn 一次）。埋點代码照写，配置就绪后自动开始上报，業務零特殊处理。

tracker 配置项另有 autoPageView 子开关（預設开），完整字段见配置项参考。

兩種上報通道（集團 WebSDK / 自建後端）

system/info.tracker 的配置形态決定走哪条通道，二選一：

通道	後端下发字段	上报形态
集團 WebSDK（預設）	`{ appId, channel, encryptedConfig }`	懒加载 vendored WebSDK，AES 密文配置内解上报域名 + HMAC 签名，发到集團 DMP
自建後端	`{ endpoint, siteKey }`	明文 JSON 批量直连自有後端（不加载 WebSDK、不加密签名，埋點非敏感、要輕）

優先級：endpoint 存在 → 自建通道；否則 appId+encryptedConfig → 集團通道。業務侧完全無感——useTracker().track() / 自动 pageView / :track 全部按配置自動分流。

自建通道行為（utils/tracker/self-hosted.ts）：事件入記憶體佇列，滿量（預設 10 条）/ 定時（預設 5s）/ 頁面隱藏（visibilitychange hidden）/ 卸載（pagehide）时批量 flush；navigator.sendBeacon 优先（卸載期可靠）、fetch keepalive 兜底；全程 client-only + 失敗靜默。上报 body：

{
  "site": "<siteKey>",
  "context": { "session_id": "5f0c…", "referrer": "https://www.google.com/", "landing_page": "/movie/1", "utm_source": "google", "utm_medium": "cpc", "screen": "1920x1080", "lang": "zh-CN", "tz": "Asia/Shanghai" },
  "events": [
    { "event": "appPageView", "uid": "", "device_id": "d1", "sid": "s1", "page": "/movie", "payload": { "page_key": "home" }, "ts": 1752640000000 }
  ]
}

context 是整批共用的造訪上下文（framework#415），沒值的鍵不寫：

session_id：工作階段 ID，30 分鐘無活動換新（userStore.getSessionId()，localStorage 跨分頁共享）；每次 flush 即時取
referrer / landing_page / utm_source|medium|campaign|term|content：來源、落地頁路徑與落地 UTM。落地頁與 UTM 取本次文件的落地 URL（navigation timing），上報器晚於 SPA 跳轉建立也不會遺失（landing_page 自 framework#417）
首觸欄位只隨本次頁面載入觀測到的第一個工作階段發送（framework#417）：長開的頁面閒置超過 30 分鐘換了新工作階段後，之後的批次不再帶 referrer / landing_page / utm_*，新工作階段按直接造訪處理，不會被歸到舊來源；screen / lang / tz 每批都帶
screen / lang / tz：螢幕尺寸、瀏覽器語言、時區

事件列的 sid 是頁面載入級 ID（每次重新整理換新），與 session_id 不是一回事。來源歸因是工作階段級的：後端應按 session_id 取首次出現的 referrer / UTM，本站網域的 referrer 視為站內跳轉。

後端按 body.site 校驗站點、批次落庫即可（參考實作：bayverse bay-api POST /track/batch）。

自動埋點（tracker.client 插件）

client hydration 後，tracker.client 插件在 tracker 設定就緒時延遲載入 WebSDK 並 init：

appPageView：router.afterEach 自動上報（預設開，autoPageView: false 關閉）——普通頁面流量統計零程式碼，帶業務語義 page_key（route meta）
notifyPageLoad：SPA 路由跳轉完成（page:finish）自動通知 SDK 開始新頁面統計（首屏歸 SDK 生命週期採集，自動跳過）——業務無需關心
登入態聯動：watch token → setUid；渠道變化 → setContext({ channel })
SSR 渲染了 error.vue 的工作階段不上報；SDK 載入 / 上報失敗一律吞掉（console.error），絕不打斷業務

SDK 自動採集事件

WebSDK v1.1.6 起 init 成功後自動採集以下事件，業務與 framework 均無需手動上報：

事件	說明
`app_page_view`	頁面瀏覽（首屏 + SPA 路由變化，URL 級）
`page_click`	頁面點擊（自動補視口 / 捲動 / 座標衍生欄位）
`app_lifecycle`	應用生命週期（cold_start / web_load / foreground 等）
`sdk_init`	SDK 初始化完成
`network_state_change`	網路狀態變化
`app_session_summary`	工作階段結束摘要（停留時長 / 頁面數 / 點擊數 / 捲動行為）

自動採集事件帶 is_sdk_auto_collected: 1 標記，與手動 track 的業務語義事件（字典 page_key / page_name）並行共存、資料側按標記區分——所以 framework 的自動 appPageView 仍保留（資料報表的字典欄位依賴它）。舊版的 autoPageClick 選項已隨本次升級移除：SDK 自動 page_click 欄位更全且預設開啟。

自訂事件（useTracker）

const { track } = useTracker()
track('appPageView', { page_key: 'home', page_name: '首頁' })

event 接受 28 個 WebSdkEvent 預置枚舉 + 任意自訂字串（涵蓋導覽 / 推薦 / 內容 / 搜尋 / 廣告 / IM 等域，保留枚舉補全提示）。自訂事件名（如 sign_up / favorite，snake_case）僅自建通道透傳入庫；集團 WebSDK 通道只認預置枚舉、枚舉外名 dev 警告後忽略。

禁止直接呼叫 window.WebSDK —— useTracker 做了 gate（設定未就緒自動 no-op）+ 延遲載入 + 容錯，裸呼叫在設定缺失時會報錯。

內容埋點（`:track`，opt-in）

SwLink / SwButton 支援 :track prop，一個 prop 搞定內容卡片的曝光 + 點擊（不傳零行為）：

<script setup>
const base = { item_id: '123', item_type: 'video', item_name: '片名', parent_item_id: '', page_key: 'home', page_name: '首頁' }
</script>

<template>
  <SwLink to="/movie/123" :track="{
    exposure: { event: 'appPageitemExposure', payload: base },
    click:    { event: 'appPageitemClick',    payload: { ...base, position: 1 } },
  }">…</SwLink>
</template>

同一元素曝光與點擊的業務欄位（item_id / page_key 等）須一致，否則資料側串不起來
event 按場景配對：推薦流（有 recommend_trace_id）用 recommendListView / recommendListClick；普通內容用 appPageitemExposure / appPageitemClick
播放器 / 影片流的 :track.video 只填內容欄位，時長 / 進度 / 行為時機由元件自動補，不要在業務側手算

通用曝光偵測（useExposure）

業務自有打點 SDK 或非標場景，用 useExposure() 拿「進視口一次」的時機自行上報（逃生艙）。

事件欄位細節

28 個事件各自的 payload 欄位（如 appPageView 的 page_key / page_load_time、videoEvent 的 play_progress 等）查集團 WebSDK 官網：

http://34.146.148.117:8033/web/getting-started.html