簡(jiǎn)介Tracking Master 是一款面向 Bludit 扁平文件 CMS 用戶與插件開(kāi)發(fā)者的開(kāi)源網(wǎng)絡(luò)分析跟蹤插件重點(diǎn)解決輕量站點(diǎn)在不依賴數(shù)據(jù)庫(kù)的前提下統(tǒng)計(jì)訪問(wèn)量、頁(yè)面瀏覽與用戶來(lái)源的問(wèn)題并提供多供應(yīng)商分析服務(wù)的接入思路。壓縮包共 12 個(gè)文件約 17KB以 JSON 配置與元數(shù)據(jù)、PHP 插件入口、CSS 樣式、JPG 圖片、Markdown 說(shuō)明及 LICENSE 授權(quán)文本為主其中 PHP 承載插件邏輯JSON 負(fù)責(zé)配置組織CSS 與圖片用于界面呈現(xiàn)說(shuō)明和授權(quán)文件則幫助理解使用邊界。已有 481 人學(xué)習(xí)下載適合關(guān)注網(wǎng)站統(tǒng)計(jì)、隱私控制與開(kāi)源實(shí)踐的中初級(jí)站長(zhǎng)及插件開(kāi)發(fā)者參考。讀者可從中了解 Bludit 插件的基本結(jié)構(gòu)、多供應(yīng)商跟蹤的配置方式以及開(kāi)源項(xiàng)目的授權(quán)與版本管理特征為自定義統(tǒng)計(jì)需求、替換分析服務(wù)或排查集成問(wèn)題提供可復(fù)用的樣本。1. 從一次歸因數(shù)據(jù)對(duì)不上說(shuō)起Tracking Master 到底解決什么投放后臺(tái)顯示轉(zhuǎn)化 1200分析后臺(tái)顯示 860兩邊都號(hào)稱統(tǒng)計(jì)的是同一批落地頁(yè)。排查到凌晨才發(fā)現(xiàn)兩套埋點(diǎn)各寫(xiě)各的事件名一個(gè)用signup_success一個(gè)用signUpSuccess失敗重試一邊三次一邊不重試去重鍵一邊用設(shè)備號(hào)一邊用會(huì)話號(hào)。這種對(duì)不上的賬在同時(shí)接了兩家以上網(wǎng)絡(luò)分析供應(yīng)商的項(xiàng)目里幾乎是常態(tài)。Tracking Master 就是一個(gè)沖這個(gè)場(chǎng)景做的開(kāi)源軟件一個(gè)多供應(yīng)商網(wǎng)絡(luò)分析跟蹤器把「事件長(zhǎng)什么樣、什么時(shí)候發(fā)、發(fā)失敗怎么辦、發(fā)給誰(shuí)」從業(yè)務(wù)代碼里剝離出來(lái)做成一層統(tǒng)一跟蹤層底下掛多個(gè)供應(yīng)商適配器。業(yè)務(wù)側(cè)只調(diào)一次track()底層可以并行上報(bào)多家也可以按配置灰度切換、降級(jí)跳過(guò)。它適合手上有中大型前端或客戶端項(xiàng)目、已經(jīng)接了不止一家分析或歸因平臺(tái)、又不愿意讓埋點(diǎn)調(diào)用散落在幾十個(gè)業(yè)務(wù)文件里的團(tuán)隊(duì)如果你只有一個(gè)供應(yīng)商、事件量也很小直接用它反而多一層抽象。2. 架構(gòu)拆解Provider 抽象層怎么把多家供應(yīng)商塞進(jìn)一套接口多供應(yīng)商項(xiàng)目最容易走歪的地方是把「切換供應(yīng)商」做成 if-else。今天接 A 家寫(xiě)一個(gè)if (vendor a)明天接 B 家再加一個(gè)分支三個(gè)月后這段代碼沒(méi)人敢動(dòng)。Tracking Master 的骨架是反過(guò)來(lái)設(shè)計(jì)的上層只認(rèn)一套事件模型和一套發(fā)送契約任何供應(yīng)商都必須先被包裝成符合契約的 Provider才允許掛進(jìn)運(yùn)行時(shí)。這一章拆的就是這層契約長(zhǎng)什么樣、倉(cāng)庫(kù)里怎么分包、每個(gè)包該放什么。2.1 三層職責(zé)劃分Core、Provider、Transport整個(gè)運(yùn)行時(shí)被切成三層邊界很清楚改任何一層都不會(huì)牽動(dòng)另外兩層。Core 層是調(diào)度中樞負(fù)責(zé)事件構(gòu)造、字段歸一化、冪等鍵生成、隊(duì)列管理與重試策略。它不知道任何供應(yīng)商的存在只認(rèn)Provider接口。換句話說(shuō)Core 是可以脫離具體供應(yīng)商單獨(dú)跑測(cè)試的這一點(diǎn)在做單元測(cè)試時(shí)非常省事。Provider 層是適配器一家供應(yīng)商一個(gè)包。它干三件事把統(tǒng)一事件翻譯成該供應(yīng)商的請(qǐng)求體、處理這家特有的鑒權(quán)和簽名、把響應(yīng)里的錯(cuò)誤碼翻譯成統(tǒng)一的SendResult。凡是「只有這家才有的怪癖」全部關(guān)在這個(gè)包里不許外溢。Transport 層是最底下的發(fā)送通道抽出來(lái)是因?yàn)闉g覽器、Node、小程序、客戶端 WebView 的下發(fā)方式差別很大。瀏覽器要優(yōu)先用navigator.sendBeacon處理頁(yè)面卸載Node 側(cè)走h(yuǎn)ttp/https客戶端要走原生橋。常見(jiàn)做法是給 Transport 定義一個(gè)極窄的接口收到 URL、headers、body返回狀態(tài)碼或異常別的一概不管。三層之間只允許自上而下調(diào)用Provider 不能反向去讀 Core 的內(nèi)部狀態(tài)。這條約束聽(tīng)著死板但它保證了新增供應(yīng)商時(shí)你只需要看一個(gè)包不用滿倉(cāng)庫(kù)找耦合點(diǎn)。2.2 倉(cāng)庫(kù)目錄六個(gè)包各自負(fù)責(zé)什么monorepo 結(jié)構(gòu)用 pnpm workspace 管構(gòu)建工具常見(jiàn)選擇是 tsup 或 rollup輸出 ESM CJS 雙格式方便瀏覽器和 Node 同時(shí)消費(fèi)。落到目錄上大概是這個(gè)樣子tracking-master/ ├── pnpm-workspace.yaml ├── packages/ │ ├── core/ # 事件模型、隊(duì)列、重試、采樣、生命周期 │ │ ├── src/ │ │ │ ├── tracker.ts # 對(duì)外入口track/identify/flush │ │ │ ├── queue.ts # 批量隊(duì)列與 flush 觸發(fā) │ │ │ ├── event.ts # 事件構(gòu)造與字段歸一化 │ │ │ └── retry.ts # 退避策略 │ │ └── package.json │ ├── provider-base/ # Provider 接口定義 抽象基類 │ ├── provider-alpha/ # 供應(yīng)商 A 適配器 │ ├── provider-beta/ # 供應(yīng)商 B 適配器 │ ├── provider-gamma/ # 供應(yīng)商 C 適配器 │ └── transport/ # fetch / sendBeacon / node-http 適配 ├── examples/ │ ├── web-demo/ # 瀏覽器最小可跑示例 │ └── node-demo/ # 服務(wù)端上報(bào)示例 └── scripts/ └── mock-server.ts # 本地驗(yàn)收用的假接收端provider-base單獨(dú)成包是個(gè)關(guān)鍵決定。如果把它塞進(jìn)core那所有 Provider 包都會(huì)依賴corecore又要在運(yùn)行時(shí)去 import 各家 Provider很容易繞成循環(huán)依賴。抽出來(lái)之后依賴方向變成單向core → provider-base ← provider-alpha干凈很多。examples目錄別跳過(guò)多供應(yīng)商項(xiàng)目最怕的就是「文檔說(shuō)支持實(shí)際跑不起來(lái)」。倉(cāng)庫(kù)里帶一個(gè)能一鍵啟動(dòng)的 web-demo比寫(xiě)十頁(yè) README 管用。2.3 Provider 接口約定與生命周期供應(yīng)商適配器要實(shí)現(xiàn)的接口非常薄薄到你可以半小時(shí)包一家新的// packages/provider-base/src/types.ts export interface ProviderConfig { enabled: boolean; // 灰度開(kāi)關(guān)false 時(shí)整條鏈路直接跳過(guò) endpoint: string; // 該供應(yīng)商的接收地址 apiKey?: string; batchSize?: number; // 這家允許的單批上限各家不一樣 timeoutMs?: number; } export interface SendResult { ok: boolean; retryable: boolean; // 關(guān)鍵區(qū)分「網(wǎng)絡(luò)抖動(dòng)」和「參數(shù)錯(cuò)了」 status?: number; message?: string; } export interface Provider { readonly name: string; init(cfg: ProviderConfig): Promisevoid; send(events: TrackEvent[]): PromiseSendResult; flush?(): Promisevoid; // 有本地緩沖的供應(yīng)商才需要實(shí)現(xiàn) }retryable這個(gè)字段是整個(gè)設(shè)計(jì)里最值得說(shuō)的一處。HTTP 500、超時(shí)、連接重置屬于可重試400、401、422 屬于不可重試——參數(shù)寫(xiě)錯(cuò)了你重試一百次也是錯(cuò)的只會(huì)把隊(duì)列堵死。把判斷權(quán)交給 Provider是因?yàn)橹挥兴雷约义e(cuò)誤碼的含義Core 層不該去背別人家的錯(cuò)誤碼表。生命周期有嚴(yán)格順序init()全部成功之后才允許send()。實(shí)踐中常見(jiàn)做法是給init加一個(gè)超時(shí)保護(hù)比如 3 秒沒(méi)完成就標(biāo)記為「就緒但降級(jí)」讓其它供應(yīng)商先跑別讓一家的初始化把整條鏈路卡住。這個(gè)細(xì)節(jié)在第 5 章會(huì)作為一個(gè)具體的坑展開(kāi)。flush()是可選方法只對(duì)帶本地緩沖的供應(yīng)商標(biāo)記有意義。有些供應(yīng)商的 SDK 自己會(huì)攢批那適配器就得在頁(yè)面卸載前把它的緩沖沖一遍否則最后一批數(shù)據(jù)就留在內(nèi)存里跟著頁(yè)面一起沒(méi)了。3. 跑起來(lái)本地環(huán)境、配置和第一條上報(bào)事件架構(gòu)看完接下來(lái)是讓它真的動(dòng)起來(lái)。這一章按「裝依賴 → 寫(xiě)配置 → 發(fā)第一個(gè)事件 → 本地驗(yàn)收」的順序走一遍中間會(huì)解釋每個(gè)參數(shù)改了會(huì)發(fā)生什么以及失敗時(shí)該去哪里看。整套流程在一臺(tái)普通開(kāi)發(fā)機(jī)上十分鐘內(nèi)能走完。3.1 環(huán)境準(zhǔn)備與依賴安裝Node 版本建議 18 以上原因是 Transport 層在 Node 側(cè)會(huì)用到全局fetch低版本還得額外裝 polyfill平白多一層坑。包管理器跟著倉(cāng)庫(kù)走用 pnpm別用 npm 裝——workspace 里的workspace:*協(xié)議 npm 處理起來(lái)會(huì)報(bào)錯(cuò)。# 克隆后先確認(rèn) pnpm 版本倉(cāng)庫(kù)通常在 package.json 的 packageManager 字段里鎖了 corepack enable pnpm install # 全量構(gòu)建產(chǎn)出 dist 供 examples 引用 pnpm -r build # 跑測(cè)試先確認(rèn)基線是綠的再動(dòng)手改 pnpm -r testpnpm -r是遞歸執(zhí)行會(huì)按拓?fù)漤樞蚺苊總€(gè)包。構(gòu)建順序很重要provider-base必須先于core構(gòu)建完否則core編譯時(shí)會(huì)找不到類型聲明。如果你的構(gòu)建報(bào)「Cannot find module tracking/provider-base」八成是跳過(guò)了這一步直接進(jìn)某個(gè)子包跑 build。測(cè)試用的是 vitest跑起來(lái)很快。基線不綠就先別改代碼先看是不是 Node 版本問(wèn)題——這類環(huán)境差異導(dǎo)致的紅燈排查起來(lái)最費(fèi)時(shí)間。3.2 配置文件一份 providers 數(shù)組怎么讀初始化配置決定了整個(gè)運(yùn)行時(shí)的行為寫(xiě)清楚每個(gè)字段比背 API 有用得多// examples/web-demo/src/tracker.ts import { createTracker } from tracking/core; import { createAlphaProvider } from tracking/provider-alpha; import { createBetaProvider } from tracking/provider-beta; export const tracker createTracker({ appId: demo-app, // 全局公共屬性會(huì)合并進(jìn)每一條事件的 context context: { platform: web, release: 1.0.0, }, // 采樣1 表示全量0.1 表示只上報(bào) 10%調(diào)試期建議先設(shè) 1 sampleRate: 1, queue: { maxBatch: 20, // 單批最多幾條取所有供應(yīng)商 batchSize 的最小值 flushIntervalMs: 5000, // 定時(shí)沖刷間隔 maxQueueSize: 500, // 隊(duì)列上限超了丟最舊的防止內(nèi)存漲爆 }, providers: [ createAlphaProvider({ enabled: true, endpoint: https://alpha.example-analytics.test/collect, apiKey: process.env.ALPHA_KEY, batchSize: 20, }), createBetaProvider({ enabled: false, // 灰度階段先關(guān)掉驗(yàn)證完再打開(kāi) endpoint: https://beta.example-analytics.test/v2/events, apiKey: process.env.BETA_KEY, batchSize: 50, }), ], });queue.maxBatch的取值有個(gè)講究它必須小于等于所有啟用供應(yīng)商里最小的batchSize。A 家允許 20 條一批、B 家只允許 10 條你設(shè)成 20 就會(huì)讓 B 家那邊整批被拒。手工對(duì)齊容易忘常見(jiàn)做法是在createTracker里做個(gè)校驗(yàn)取最小值并打一條 warn 日志。sampleRate是全局采樣采樣發(fā)生在入隊(duì)之前所以被采樣掉的事件不會(huì)占用隊(duì)列空間。調(diào)試階段先設(shè) 1等上線前再按量級(jí)往下調(diào)。這里有個(gè)容易忽略的點(diǎn)采樣和去重的關(guān)系在第 5 章會(huì)單獨(dú)講它會(huì)直接影響轉(zhuǎn)化數(shù)據(jù)。enabled: false不是把 Provider 從數(shù)組里刪掉而是保留實(shí)例但跳過(guò)發(fā)送。這個(gè)區(qū)別在灰度切換時(shí)很實(shí)用——你可以通過(guò)遠(yuǎn)端配置熱改這個(gè)布爾值不用發(fā)版。3.3 第一個(gè)事件從 track 調(diào)用到網(wǎng)絡(luò)請(qǐng)求發(fā)出配置就緒發(fā)一條事件看看// 業(yè)務(wù)側(cè)只認(rèn)這一個(gè)調(diào)用不關(guān)心底下有幾家供應(yīng)商 tracker.track(signup_success, { plan: pro, amount: 199, currency: CNY, }); // 主動(dòng)沖刷本地調(diào)試時(shí)用線上靠定時(shí)器和頁(yè)面卸載觸發(fā) await tracker.flush(manual);調(diào)用進(jìn)到 Core 之后實(shí)際發(fā)生的事是先補(bǔ)全eventId、ts、anonId這些公共字段再合并context和本次props然后入隊(duì)最后按flushIntervalMs或隊(duì)列長(zhǎng)度觸發(fā)沖刷。沖刷時(shí) Core 會(huì)把同一批事件分發(fā)給所有enabled為 true 的 Provider各自翻譯成自己的請(qǐng)求體并發(fā)發(fā)出。track()是同步返回的不阻塞業(yè)務(wù)代碼這一點(diǎn)很重要——埋點(diǎn)絕不能在主線程上 await 網(wǎng)絡(luò)請(qǐng)求。真正需要等結(jié)果的地方比如單測(cè)、腳本化驗(yàn)收才用flush()拿到 Promise。建議在本地先把flushIntervalMs調(diào)到 1000這樣你能在 Network 面板里快速看到請(qǐng)求。等邏輯驗(yàn)證完再調(diào)回 5000線上頻繁小批量上報(bào)對(duì)服務(wù)端不友好。如果想驗(yàn)證字段是否正確可以在 Provider 的send里臨時(shí)打一行日志把翻譯后的請(qǐng)求體打出來(lái)。這比在瀏覽器里翻 payload 快得多尤其是嵌套結(jié)構(gòu)。3.4 用本地 mock 服務(wù)驗(yàn)收上報(bào)內(nèi)容真的往供應(yīng)商地址發(fā)請(qǐng)求在開(kāi)發(fā)階段既慢又不方便斷言。倉(cāng)庫(kù)的scripts/mock-server.ts就是干這個(gè)的起一個(gè)本地接收端把收到的 body 落盤# 起本地接收端默認(rèn)監(jiān)聽(tīng) 8787 pnpm tsx scripts/mock-server.ts --port 8787 --out ./tmp/payloads # 另開(kāi)一個(gè)終端跑 demo把 endpoint 指過(guò)來(lái) cd examples/web-demo pnpm dev// scripts/mock-server.ts 的核心邏輯收什么存什么 import { createServer } from node:http; import { writeFileSync, mkdirSync } from node:fs; const outDir process.argv.includes(--out) ? ./tmp/payloads : ./tmp; mkdirSync(outDir, { recursive: true }); createServer((req, res) { let raw ; req.on(data, (c) (raw c)); req.on(end, () { // 按供應(yīng)商名分文件存方便對(duì)比同一批事件被翻譯成了什么 const vendor new URL(req.url ?? /, http://x).searchParams.get(v) ?? unknown; const name ${vendor}-${Date.now()}.json; writeFileSync(${outDir}/${name}, raw || {}); res.writeHead(204).end(); }); }).listen(8787, () console.log(mock listening on 8787));驗(yàn)收的重點(diǎn)不是「請(qǐng)求發(fā)出去了」而是「不同供應(yīng)商收到的字段語(yǔ)義一致」。打開(kāi)tmp/payloads里的兩個(gè)文件對(duì)比A 家的event_name和 B 家的eventName是不是同一個(gè)值時(shí)間戳單位是不是都是毫秒金額有沒(méi)有一邊是元一邊是分。這類差異一旦漏到線上就是開(kāi)頭說(shuō)的那種「兩邊報(bào)表對(duì)不上」。--port和--out兩個(gè)參數(shù)按需改就行端口沖突時(shí)換一個(gè)輸出目錄建議放tmp并加進(jìn).gitignore別把 payload 提交上去。4. 核心模塊代碼事件模型、批量隊(duì)列與歸因回傳跑通之后再回頭看內(nèi)部會(huì)發(fā)現(xiàn)真正決定這套東西能不能長(zhǎng)期用的是三塊代碼事件模型有沒(méi)有把字段統(tǒng)一住、隊(duì)列有沒(méi)有把失敗處理好、歸因參數(shù)有沒(méi)有正確地從落地頁(yè)帶到后續(xù)所有事件。這一章逐個(gè)拆代碼都是可以照著抄的骨架。4.1 統(tǒng)一事件模型字段歸一化與冪等鍵事件模型是整個(gè)系統(tǒng)的地基。字段不一致上層做得再好都白搭// packages/core/src/event.ts export interface TrackEvent { eventId: string; // 冪等鍵去重靠它 name: string; // 歸一化事件名統(tǒng)一小寫(xiě)下劃線 ts: number; // 客戶端毫秒時(shí)間戳 anonId: string; // 匿名設(shè)備/瀏覽器標(biāo)識(shí) userId?: string; // 登錄后綁定 props: Recordstring, unknown; // 業(yè)務(wù)自定義屬性 context: Recordstring, unknown; // 頁(yè)面、設(shè)備、版本等公共屬性 } // 事件名歸一化把 signUpSuccess、sign-up-success 全部收斂成 sign_up_success export function normalizeName(raw: string): string { return raw .replace(/([a-z0-9])([A-Z])/g, $1_$2) // 駝峰轉(zhuǎn)下劃線 .replace(/[-\s]/g, _) .toLowerCase(); } // 冪等鍵同一用戶的同一事件在同一毫秒只允許一條 export function buildEventId(input: { anonId: string; name: string; ts: number }): string { return ${input.anonId}:${input.name}:${input.ts}; }normalizeName是必須的。各家供應(yīng)商對(duì)事件名的大小寫(xiě)和分隔符要求不一樣A 家建議下劃線、B 家允許駝峰如果不在 Core 層統(tǒng)一同一個(gè)業(yè)務(wù)動(dòng)作在不同后臺(tái)會(huì)變成兩個(gè)完全不同的指標(biāo)中間再想合并就麻煩了。buildEventId用anonId name ts三元組目的是擋住重復(fù)上報(bào)。同一毫秒內(nèi)同一個(gè)用戶觸發(fā)同一個(gè)事件在真實(shí)場(chǎng)景里基本只有一種可能重復(fù)調(diào)用。用這個(gè)鍵在 Provider 側(cè)或服務(wù)端做一次去重能擋掉相當(dāng)一部分臟數(shù)據(jù)。context和props分開(kāi)放是因?yàn)樗鼈兊纳芷诓煌?。context是初始化時(shí)給的公共屬性可能中途更新比如用戶切換了語(yǔ)言但整體變化少props是一次性的每條事件都不一樣。分成兩個(gè)字段Provider 翻譯時(shí)也好處理——有的供應(yīng)商要求公共屬性放在請(qǐng)求頭或者 query 上有的要求平鋪進(jìn) body。4.2 批量隊(duì)列與重試flush 的四個(gè)觸發(fā)條件隊(duì)列這塊代碼不長(zhǎng)但要處理清楚的邊界情況不少// packages/core/src/queue.ts type FlushReason interval | full | manual | unload; export class EventQueue { private buffer: TrackEvent[] []; private inFlight false; constructor( private providers: Provider[], private maxBatch: number, private maxQueueSize: number, private retry: RetryPolicy, ) {} push(evt: TrackEvent) { // 隊(duì)列滿時(shí)丟最舊的埋點(diǎn)數(shù)據(jù)可以丟但不能讓內(nèi)存漲爆 if (this.buffer.length this.maxQueueSize) this.buffer.shift(); this.buffer.push(evt); } async flush(reason: FlushReason): Promisevoid { // 單飛同一時(shí)刻只允許一個(gè)沖刷在跑否則會(huì)重復(fù)上報(bào) if (this.inFlight) return; if (!this.buffer.length) return; const batch this.buffer.splice(0, this.maxBatch); this.inFlight true; try { const results await Promise.allSettled( this.providers .filter((p) p.isEnabled()) .map((p) p.send(batch)), ); // 只把「可重試」的失敗塞回隊(duì)首不可重試的直接丟避免堵死隊(duì)列 const needRetry results.some( (r) r.status rejected || (r.value.ok false r.value.retryable), ); if (needRetry this.retry.canRetry()) { this.buffer.unshift(...batch); await this.retry.wait(); } } finally { this.inFlight false; } } }inFlight這個(gè)鎖是血淚經(jīng)驗(yàn)換來(lái)的。沒(méi)有它的時(shí)候定時(shí)刷新和手動(dòng)flush()很容易撞在一起同一批事件被發(fā)兩次后臺(tái)數(shù)據(jù)直接翻倍而且還很難復(fù)現(xiàn)——因?yàn)樗蕾嚂r(shí)序。加上這把鎖之后并發(fā)調(diào)用會(huì)直接返回簡(jiǎn)單粗暴但有效。flush有四個(gè)觸發(fā)點(diǎn)缺一不可定時(shí)器到點(diǎn)interval、隊(duì)列達(dá)到批量上限full、手動(dòng)調(diào)用manual、頁(yè)面卸載unload。第四個(gè)最容易被忘而它恰恰是最后一批數(shù)據(jù)能不能落地的關(guān)鍵。卸載場(chǎng)景一般走sendBeacon因?yàn)槠胀╢etch在頁(yè)面銷毀時(shí)會(huì)被瀏覽器掐斷。重試策略用指數(shù)退避常見(jiàn)配置是首次 1 秒、每次翻倍、最多 3 到 5 次、單次上限 30 秒。別配無(wú)限重試一個(gè)壞掉的端點(diǎn)會(huì)把隊(duì)列塞滿最后正常的供應(yīng)商也被拖累。4.3 歸因參數(shù)回傳首觸與末觸的持久化選擇網(wǎng)絡(luò)分析里最影響結(jié)論的是歸因參數(shù)有沒(méi)有被正確保存下來(lái)。從落地頁(yè) URL 上的utm_*、click_id這類參數(shù)抓起存下來(lái)之后每條事件都帶上// packages/core/src/attribution.ts const STORAGE_KEY tm_attribution; interface Attribution { firstTouch?: Recordstring, string; // 首次進(jìn)入時(shí)的參數(shù) lastTouch?: Recordstring, string; // 最近一次進(jìn)入時(shí)的參數(shù) capturedAt: number; } export function captureAttribution( search: string, store: PickStorage, getItem | setItem, keys [utm_source, utm_medium, utm_campaign, click_id], ): Attribution | null { const params new URLSearchParams(search); const hit: Recordstring, string {}; for (const k of keys) { const v params.get(k); if (v) hit[k] v; } if (!Object.keys(hit).length) { // 本次沒(méi)帶參數(shù)返回已存的保證后續(xù)事件仍能掛上歷史歸因 const raw store.getItem(STORAGE_KEY); return raw ? (JSON.parse(raw) as Attribution) : null; } const prev store.getItem(STORAGE_KEY); const old: Attribution prev ? JSON.parse(prev) : { capturedAt: Date.now() }; const next: Attribution { firstTouch: old.firstTouch ?? hit, // 首觸一旦定下就不再覆蓋 lastTouch: hit, // 末觸每次都更新 capturedAt: Date.now(), }; store.setItem(STORAGE_KEY, JSON.stringify(next)); return next; }這段的關(guān)鍵決策是「首觸不覆蓋、末觸每次更新」。做渠道效果評(píng)估通常看首觸做再營(yíng)銷效果看末觸兩個(gè)都存下來(lái)后面按需取比只存一個(gè)再回頭補(bǔ)要省事得多。存儲(chǔ)介質(zhì)要挑Web 端用localStorage但要注意它有容量上限且可能被用戶清掉客戶端一般落本地?cái)?shù)據(jù)庫(kù)或 key-value如果涉及跨端打通還得考慮服務(wù)端回傳兜底。存儲(chǔ)失敗隱私模式、配額滿必須有 try-catch不能讓歸因失敗把主流程帶崩。keys參數(shù)做成可配置是因?yàn)椴煌瑯I(yè)務(wù)的渠道參數(shù)名不一樣硬編碼在代碼里等于給自己上鎖。上線前把這份 key 列表跟投放側(cè)對(duì)一遍別一邊叫utm_campaign一邊叫campaign_id這種不對(duì)齊到了月底對(duì)賬時(shí)最要命。5. 避坑與排查多供應(yīng)商接入最容易翻車的五個(gè)位置這套東西跑通不難難的是跑穩(wěn)。下面五條都是在多供應(yīng)商場(chǎng)景里真實(shí)會(huì)撞上的問(wèn)題按「現(xiàn)象 → 原因 → 解決」寫(xiě)遇到類似癥狀可以直接對(duì)照。5.1 事件量莫名翻倍初始化被執(zhí)行了兩次現(xiàn)象后臺(tái)看到的事件數(shù)是預(yù)期的接近兩倍且兩條記錄的時(shí)間戳只差幾毫秒eventId卻不同。原因通常有兩個(gè)一是模塊被重復(fù)引入SPA 里路由切換、微前端子應(yīng)用各自初始化了一遍 tracker二是熱更新HMR在開(kāi)發(fā)環(huán)境反復(fù)執(zhí)行模塊頂層代碼把舊的實(shí)例留著沒(méi)銷毀。解決把 tracker 實(shí)例掛到全局單例上初始化前先判斷是否存在同時(shí)導(dǎo)出destroy()清掉定時(shí)器和事件監(jiān)聽(tīng)。開(kāi)發(fā)環(huán)境的 HMR 問(wèn)題在import.meta.hot.dispose里調(diào)一次destroy()就能解決大半。另外buildEventId用anonId name ts而不是隨機(jī) UUID就是為了在這種場(chǎng)景下還能靠服務(wù)端去重兜一層。5.2 同一個(gè)動(dòng)作在兩家后臺(tái)變成兩個(gè)指標(biāo)現(xiàn)象A 家后臺(tái)能看到signup_successB 家后臺(tái)只有一條signUpSuccess兩邊漏斗對(duì)不上。原因是沒(méi)有在 Core 層做事件名歸一化或者做了一半——Provider 翻譯時(shí)又自己轉(zhuǎn)了一次大小寫(xiě)轉(zhuǎn)出兩套規(guī)則。解決歸一化只在 Core 的normalizeName里做一次Provider 層禁止再動(dòng)事件名只負(fù)責(zé)字段映射。同時(shí)維護(hù)一張「業(yè)務(wù)事件名 → 各供應(yīng)商事件名」的映射表映射表集中在一個(gè)文件里改的時(shí)候一眼能看到全貌。上線前用 mock server 抓兩份 payload 做逐字段 diff是最直接的驗(yàn)證手段。5.3 頁(yè)面關(guān)閉時(shí)最后一批數(shù)據(jù)丟了現(xiàn)象用戶點(diǎn)支付完成后立刻關(guān)頁(yè)面支付成功事件在后臺(tái)查不到但日志里明明有track()調(diào)用。原因是走的是普通fetch頁(yè)面卸載時(shí)請(qǐng)求被瀏覽器中斷或者隊(duì)列里還有數(shù)據(jù)沒(méi)到刷新間隔。解決監(jiān)聽(tīng)visibilitychange在hidden狀態(tài)觸發(fā)一次flush(unload)這條路徑上強(qiáng)制走sendBeacon。注意sendBeacon有 64KB 的體積限制超了會(huì)直接返回 false 且不報(bào)錯(cuò)所以卸載時(shí)的批量要單獨(dú)控制得小一些比如 10 條以內(nèi)。pagehide比beforeunload在移動(dòng)端更可靠?jī)蓚€(gè)都監(jiān)聽(tīng)更保險(xiǎn)。5.4 批量太大被供應(yīng)商靜默丟棄現(xiàn)象單條事件發(fā)得出去批量發(fā)就沒(méi)了服務(wù)端返回 200 但后臺(tái)查無(wú)數(shù)據(jù)。原因是超過(guò)該供應(yīng)商的單批上限部分實(shí)現(xiàn)會(huì)返回成功但只處理前 N 條形成黑匣子。解決maxBatch取所有啟用供應(yīng)商batchSize的最小值并在createTracker里做斷言校驗(yàn)。同時(shí)對(duì)每個(gè) Provider 的send結(jié)果做長(zhǎng)度校驗(yàn)——如果發(fā)出去 20 條、接口只認(rèn)了 10 條得能從返回體里讀出來(lái)。接入新供應(yīng)商時(shí)第一件事就是把它的批量上限和限流閾值摸清楚寫(xiě)進(jìn)配置注釋里。5.5 采樣開(kāi)到 0.1 之后轉(zhuǎn)化數(shù)少了一截現(xiàn)象采樣率從 1 調(diào)到 0.1曝光數(shù)按比例降了但轉(zhuǎn)化數(shù)降得更多。原因是采樣發(fā)生在入隊(duì)前而轉(zhuǎn)化事件往往依賴前序曝光事件做歸因匹配前序被采樣掉轉(zhuǎn)化就成了無(wú)源之水。解決轉(zhuǎn)化類關(guān)鍵事件不參與采樣或者用「按用戶維度采樣」而不是「按事件維度采樣」——同一個(gè)anonId要么全采要么全不采保證鏈路完整。實(shí)現(xiàn)上把采樣判斷放在anonId生成之后、eventId計(jì)算之前并對(duì)標(biāo)記為critical的事件類型直接跳過(guò)采樣邏輯。改了采樣策略一定要重新對(duì)一次兩邊后臺(tái)的轉(zhuǎn)化數(shù)這是唯一靠譜的驗(yàn)證。6. 二次開(kāi)發(fā)新增一家供應(yīng)商與本地驗(yàn)證的完整路徑接第四家供應(yīng)商是這套架構(gòu)最常被考驗(yàn)的地方。如果按下面四步走還覺(jué)得疼說(shuō)明抽象層有問(wèn)題該回頭改provider-base而不是在業(yè)務(wù)里打補(bǔ)丁。第一步建包。復(fù)制provider-beta整個(gè)目錄改成provider-delta改package.json的 name 和依賴pnpm install讓 workspace 鏈接生效。第二步實(shí)現(xiàn)send重點(diǎn)是把統(tǒng)一事件翻譯成目標(biāo)請(qǐng)求體鑒權(quán)放在 headers 里別混進(jìn) body。第三步把錯(cuò)誤碼映射到retryable超時(shí)和 5xx 給 true4xx 給 false限流 429 單獨(dú)處理——給 true 但要讀Retry-After。第四步寫(xiě)單測(cè)至少要覆蓋「正常一批」「部分字段缺失」「服務(wù)端 500」「服務(wù)端 400」四種情況。// packages/provider-delta/src/index.ts export function createDeltaProvider(cfg: ProviderConfig): Provider { return { name: delta, isEnabled: () cfg.enabled, async init() { /* 校驗(yàn) apiKey 是否為空空則直接拋 */ }, async send(events) { const body { app: cfg.apiKey, // delta 要求時(shí)間戳是秒這里必須轉(zhuǎn)不能直接透?jìng)骱撩?data: events.map((e) ({ eid: e.eventId, en: e.name, t: Math.floor(e.ts / 1000), uid: e.userId ?? e.anonId, kv: { ...e.context, ...e.props }, })), }; const res await transport.post(cfg.endpoint, body, { timeoutMs: cfg.timeoutMs }); // 429 是可重試的但要走它自己的退避節(jié)奏 return { ok: res.status 300, retryable: res.status 500 || res.status 429, status: res.status }; }, }; }單位換算是這類適配里最容易翻車的一處Math.floor(e.ts / 1000)少了就會(huì)在后臺(tái)看到 1970 年的數(shù)據(jù)。字段命名映射eventId → eid建議在包內(nèi)維護(hù)一張常量表別散在 map 里。驗(yàn)證分三層單測(cè)跑邏輯mock server 跑 payload diff最后用真實(shí)地址跑一個(gè)灰度環(huán)境enabled先設(shè) false用遠(yuǎn)端配置單獨(dú)打開(kāi)給 1% 用戶。觀察一天比對(duì)這 1% 用戶在新舊兩個(gè)后臺(tái)的事件量差異超過(guò) 2% 就回滾查原因。這個(gè)流程我一般會(huì)寫(xiě)在包的 README 里誰(shuí)來(lái)接手都照著走。說(shuō)個(gè)教訓(xùn)。早些年接第三家供應(yīng)商時(shí)我圖快直接在業(yè)務(wù)代碼里加了個(gè)判斷繞過(guò)了隊(duì)列結(jié)果那家一限流就把主線程卡住頁(yè)面白屏。從那以后我每次新增 Provider都強(qiáng)制走一遍「單測(cè) → mock diff → 1% 灰度 → 差異比對(duì)」這四步一步不省。這套流程慢是慢了點(diǎn)但比線上回滾快得多。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取