打点底座

framework 把集团统一上报 WebSDK 封装为打点底座：普通页面流量统计（自动 pageView）、自定义事件（useTracker）、通用内容埋点（:track / useExposure）开箱即用。广告埋点 是底座之上的一个消费方，不是底座本身。

接入与配置

上报受双重 gate：

  1. swift.config.json 的 tracker.enabled（总开关，对应 swiftConfig.tracker）
  2. 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 跨 tab 共享）；每次 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 init 成功后会自动采集以下事件，业务与 framework 均无需手动上报：

事件说明
app_page_view页面浏览（首屏 + SPA 路由变化，URL 级）
page_click页面点击（自动补视口 / 滚动 / 坐标衍生字段）
app_lifecycle应用生命周期（cold_start / web_load / foreground 等）
sdk_initSDK 初始化完成
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