使用 fetchLater() 实现全会话分析:Modern Web Guidance 中 full-session-analytics 验收标准与实现详解
使用 fetchLater() 实现全会话分析:Modern Web Guidance 中 full-session-analytics 验收标准与实现详解
在 Web 分析场景里,真正困难的不是“采集指标”,而是“把会话最后一段、也就是用户关闭标签页或跳转离开时的数据可靠地送达服务端”。本指南以 Modern Web Guidance 仓库中的 guides/performance/full-session-analytics/expectations.md 为骨架,逐条拆解 fetchLater() 方案的验收标准,并结合同目录的 guide.md、demo.html 与自动化 grader.ts,说明每一条要求为什么成立、如何在代码中落地、以及如何被仓库的评测流水线验证。读完后你应能独立写出一个既不阻塞交互、又不破坏 bfcache 的会话级埋点实现。
一、这份 expectations.md 定义了什么样的“合格实现”
guides/performance/full-session-analytics/expectations.md 只有五条,但每一条都对应一个可被自动化断言的外部可观察行为:
| 编号 | 验收要求 | 本质约束 |
|---|---|---|
| 1 | fetchLater() 以 URL 字符串为第一个参数,可选地传 DeferredRequestInit 作为第二个参数 |
调用签名正确 |
| 2 | fetchLater() 是唯一的 beacon 发送 API,不得使用 fetch()、sendBeacon()、XMLHttpRequest 或 new Image() |
发送通道单一化 |
| 3 | 只发送一次 beacon,且发生在用户离开页面之后 | 延迟交付与去重 |
| 4 | 当调用抛出 QuotaExceededError、RangeError 或 TypeError 时必须被妥善处理 |
异常可恢复 |
| 5 | 除非项目只支持 Chromium,否则必须把 fetchLater() polyfill 打进产物 |
兼容性兜底 |
这五条构成了一个“最小但完备”的契约:正确的 API、唯一的通道、正确的时机、可控的失败、可用的降级。下面的章节按此顺序展开,并补充仓库中对应的实现证据与测试证据。
二、验收点 1:调用签名与 DeferredRequestInit
第一条要求很直白:第一个参数必须是 URL 字符串,第二个参数是可选的 DeferredRequestInit 对象。仓库中的参考实现位于 demo.html:
fetchLater(ANALYTICS_ENDPOINT, {
method: 'POST',
headers: {'content-type': 'application/json'},
body: JSON.stringify(sessionData),
signal: fetchLaterController.signal,
});
从仓库示例与 polyfill 代码可以归纳出 DeferredRequestInit 在本项目中被使用的字段:
| 字段 | 作用 | 仓库中的使用位置 |
|---|---|---|
method |
请求方法,分析上报通常为 POST |
demo.html、guide.md 示例 |
headers |
自定义请求头,例如 content-type: application/json |
同上 |
body |
序列化后的负载,通常是 JSON 字符串 | 同上 |
signal |
AbortSignal,用于在数据更新时撤销待发请求 |
同上,配合 AbortController |
activateAfter |
毫秒数,到达时间后即发送;不设置则保留到页面离开 | polyfill 的定时器分支(demo.html 第 90-92 行) |
需要注意 activateAfter 属于“分批发送”变体,同仓库的 batch-analytics-events 指南 专门用它做去抖;而在“全会话分析”这个用例里,故意不传 activateAfter,让浏览器把请求一直挂到会话结束,从而拿到最完整的时长与指标。这正是两个用例的核心差异。
guides/performance/full-session-analytics/guide.md 的 frontmatter 也声明了该指南依赖的 Web 特性:
web-feature-ids:
- fetchlater
- aborting
也就是说,AbortController/AbortSignal 的行为同样是本用例的一等公民,而非可选优化。
三、验收点 2:fetchLater() 必须是唯一的 sendBeacon 通道
第二条明确禁止 fetch()、sendBeacon()、XMLHttpRequest 和 new Image()。原因写在 guide.md 里:在 unload 事件里创建 <img> 像素点是“出了名的不可靠”,在移动端尤其如此,而且注册 unload 监听会让页面失去 bfcache 资格,反而拖累性能。
这一条在测试中被具体化为若干字符串与语法检查,见 grader.ts:
const usesXhr = code.includes('XMLHttpRequest');
const usesImage = code.includes('new Image');
const directFetch = code.includes('fetch(ANALYTICS_ENDPOINT');
const directSendBeacon = code.includes('sendBeacon(ANALYTICS_ENDPOINT');
const hasForbiddenUsage = usesXhr || usesImage || directFetch || directSendBeacon;
expect(hasForbiddenUsage).toBeFalsy();
这里有一个容易踩坑的细节:polyfill 内部确实会调用 fetch(url, ...) 和 navigator.sendBeacon(url, init.body),但它检查的是 fetch(ANALYTICS_ENDPOINT 这种“业务代码直接拿端点常量发请求”的写法。所以正确的姿势是:业务侧只出现 fetchLater(...),原始的 fetch/sendBeacon 只能存在于 polyfill 的实现体内。guide.md 也用大写强调:
Your own code MUST call
fetchLater()directly — never callfetch(),sendBeacon(), or other beacon APIs yourself.
仓库里还可以找到一个反面样例 negative-demo.html,它同时使用了 fetch(且 body 是 ReadableStream)、XMLHttpRequest、navigator.sendBeacon 以及 unload 中的 new Image(),几乎把四条禁令全部违反,可用于对照理解“为什么这样写是错的”。注意这个反例还叠加了一个隐性错误:fetchLater() 不接受 ReadableStream 作为 body,而 guide.md 的 Best Practices 也明确写了“DO NOT use a ReadableStream object for the request body, as that will error”。
四、验收点 3:只发一次,且发生在用户离开之后
第三条是整个方案的技术核心:全会话只投递一个 beacon,并且投递时机在用户离开页面之后。guide.md 给出的实现范式是“每次数据变化就中止上一次、重新排队一次”:
- 排期请求:数据一就绪就调用
fetchLater(),把负载排入队列; - 按需更新负载:用户产生更多数据或状态变化时,
abort()掉上一次排期,用最新的完整快照重新调用; - 交给浏览器:用户离开或关闭标签页时,浏览器可靠地发送“最后一次”
fetchLater()的负载。
参考实现(guide.md):
const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';
const sessionData = {
duration: 0,
id: crypto.randomUUID(),
};
let fetchLaterController = null;
function queueBeacon() {
// Abort any pending beacons before creating a new one.
if (fetchLaterController) {
fetchLaterController.abort();
}
fetchLaterController = new AbortController();
// Update session duration to the current page time.
sessionData.duration = performance.now();
// Schedule a fetch for the data payload to be sent later.
// IMPORTANT: wrap the call in a try/catch to handle quota errors.
try {
fetchLater(ANALYTICS_ENDPOINT, {
method: 'POST',
headers: {'content-type': 'application/json'},
body: JSON.stringify(sessionData),
signal: fetchLaterController.signal,
});
} catch (error) {
// Handle errors as needed.
}
}
// Update the session data and queue a new beacon every 10 seconds.
setInterval(queueBeacon, 10000);
为什么“10 秒重排一次”最终只会有一次网络请求?因为 AbortController.abort() 会把前一次排期的请求撤销,浏览器手中始终只留最新的一份。仓库的端到端测试正是这样断言的(grader.ts):
- 强制删除原生
fetchLater,让 polyfill 接管,从而“确定性地”测试延迟逻辑; - 对
navigator.sendBeacon与window.fetch打补丁,一旦提前发往/analytics/endpoint就置__prematureFlush = true; - 页面加载后 300ms 内断言没有任何提前发送,且
analyticsRequests === 0; - 然后通过
Object.defineProperty(document, 'visibilityState', ...)把可见性改为hidden并派发visibilitychange; - 最终
expect.poll(() => analyticsRequests).toBe(1)。
这段测试也解释了 polyfill 的一个关键行为差异:原生 API 依靠浏览器的 unload 处理,而 polyfill 用 visibilitychange(页面变为隐藏)作为“用户离开”的近似信号。guide.md 特意说明这是内部实现细节,业务代码不需要监听任何页面生命周期事件。
demo.html 在 guide.md 的基础上做了两点工程化增强,值得直接借鉴:
- 把
duration换算成秒(Math.round(performance.now() / 1000)),便于阅读,日志里也按秒展示; - 启动时立即调用一次
queueBeacon(),再挂setInterval(queueBeacon, 10000),避免首屏 10 秒内离开导致零数据。
五、验收点 4:QuotaExceededError、RangeError、TypeError 必须被处理
第四条要求调用方对三类异常做妥善处理。guide.md 的 Best Practices 给出了配额数量级提示:每个 origin 目前大约是 64KB,因此要尽量压缩负载以避免超限。仓库根目录的 README.md 也把这条作为“Gotchas & Quirks”的示例,说明这是被刻意记录的平台限制,而不是实现瑕疵。
对应到代码,正确的结构就是把 fetchLater() 包在 try/catch 中,并对错误做区分或至少做降级处理。grader.ts 会用正则确认存在真正的 try → fetchLater → catch 结构(grader.ts):
const tryCatchRegex = /try\s*\{[\s\S]*?fetchLater\s*\([\s\S]*?\}[\s\S]*?catch\s*(?:\(|\{)/;
expect(tryCatchRegex.test(code)).toBeTruthy();
实践上,三类错误的成因可以这样理解(这是基于 API 语义与仓库示例的归纳):
QuotaExceededError:待发请求总字节数超过 origin 配额;RangeError:例如activateAfter传入负数或非法数值范围;TypeError:例如 body 类型不被接受(ReadableStream即属此类)或参数结构非法。
因此建议在 catch 中至少做三件事:把错误上报到本地日志或降级通道、裁剪 payload 后重试、必要时直接放弃本次排期而不是无限重试。demo.html 的做法是把错误写进页面日志,便于在演示与调试时观察:
} catch (error) {
logMessage(`Quota error or failure queuing beacon: ${error.message}`);
}
六、验收点 5:polyfill 必须进包(除非只支持 Chromium)
第五条是一个交付要求:除非项目明确只支持 Chromium 系浏览器,否则 fetchLater() 的 polyfill 必须被打进 bundle。guide.md 用 {{ BASELINE_STATUS("fetchlater") }} 宏来表述 Baseline 状态,并在其后写明:如果 fetchLater() 达不到你的 Baseline 目标,就必须提供降级策略;但考虑到可靠性与性能收益,只要浏览器支持就应使用原生 API。
这个宏不是装饰。仓库的 src/core/macros.ts 定义了 BASELINE_STATUS 的渲染逻辑:它会调用 getStatusMessage(featureId, bcdKey),找不到状态时直接抛 MacroError;在 DevSite 构建目标下则输出 {{ macros.BaselineStatus('fetchlater') }} 交由上层展开。状态数据来自 src/core/baseline.ts,其中 getFeatureStatus() 会解析 feature id、归一化 baseline: 'low' | 'high' | false,mapBaseline() 再映射为 “Newly available / Widely available / Limited availability”。此外 src/core/guide-validation.ts 会检查文档里是否硬编码了 Baseline 可用性结论,一旦发现就报错并提示改用宏——这保证了所有指南的兼容性声明都能随上游数据自动更新,而不会写死过期信息。
推荐的最小 polyfill(同时出现在 guide.md 与 demo.html 中):
globalThis.fetchLater ??= function fetchLater(url, init = {}) {
let timeoutHandle;
let activated = false;
function sendNow() {
if (!(init.signal && init.signal.aborted)) {
// Use fetch keepalive if the browser supports it or if custom fetch
// parameters are specified (e.g. custom headers or methods).
// Otherwise fall back to `navigator.sendBeacon()`.
if (
'keepalive' in Request.prototype ||
init.method !== 'POST' ||
init.headers
) {
fetch(url, Object.assign({}, init, {keepalive: true}));
activated = true;
} else {
activated = navigator.sendBeacon(url, init.body);
}
}
destroy();
}
function destroy() {
document.removeEventListener('visibilitychange', sendNow);
clearTimeout(timeoutHandle);
}
if (document.visibilityState === 'hidden') {
// If the beacon was created while the page is already hidden, send data
// ASAP but wait until the next microtask to allow all sync code to run.
queueMicrotask(sendNow);
} else {
document.addEventListener('visibilitychange', sendNow);
if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
timeoutHandle = setTimeout(sendNow, init.activateAfter);
}
}
if (init.signal) {
init.signal.addEventListener('abort', destroy);
}
return {
get activated() {
return activated;
},
};
};
逐层拆解这段代码,可以看清它与原生 API 的对应关系:
globalThis.fetchLater ??=:只在不支持时安装,原生实现存在时完全不介入,符合“能在原生就用原生”的原则;init.signal && init.signal.aborted:发送前二次校验,避免“已 abort 但监听器仍在”导致的竞态;'keepalive' in Request.prototype || init.method !== 'POST' || init.headers:sendBeacon()只适合简单的 POST 字符串/Blob 且不能自定义请求头;一旦使用了自定义 header、非 POST 方法,或环境支持keepalive,就改用fetch(url, {keepalive: true})保证离页后仍可完成传输;document.visibilityState === 'hidden'分支里的queueMicrotask(sendNow):如果排期发生时页面已经隐藏,就让它在本轮同步代码执行完后立刻发送;activateAfter分支:仅在显式传入合法非负数时才设置setTimeout,这解释了为什么“全会话分析”不传该字段就能把请求一直留到离开;- 返回
{ get activated() {...} }:为分批发送场景提供“是否已真正发出”的可观测信号(本用例不依赖它,但 polyfill 与batch-analytics-events指南保持接口一致)。
grader.ts 对该条的检查同时接受“标准 polyfill 赋值”与“等价的自定义兜底赋值”两种写法(grader.ts):
const hasPolyfill =
code.includes('globalThis.fetchLater ??=') ||
/(?:globalThis|window)\.fetchLater\s*(?:\?\?=|\|\|=|=)/.test(code);
expect(hasPolyfill).toBeTruthy();
这也意味着:单纯靠特性检测 + 直接调用 fetch() 降级是不被接受的,必须提供一个保持 fetchLater() 调用形态的 shim,才能同时满足“业务代码只调用 fetchLater()”与“不支持时仍能送达”这两个目标。
七、把 Core Web Vitals 接进来
同目录的 tasks/task.md 展示了该模式在真实任务中的典型描述:使用 web-vitals 库采集 Core Web Vitals,把数据发到 /path/to/analytics/endpoint,并等到用户关闭标签页或导航离开时再发送,以确保指标值已经定稿,同时避免使用破坏 bfcache 的 legacy unload 监听。
把 web-vitals 与 fetchLater() 结合时,推荐的组合方式如下(基于 guide.md 的模式与 README.md 中“<50 LOC 的轻量兜底”原则):
- 维护一个
sessionData快照对象,包含id、duration以及各指标字段; - 每个
web-vitals回调(onLCP、onCLS、onINP等)只做一件事:更新快照字段,然后调用一次queueBeacon(); queueBeacon()内部先abort()再重建AbortController,最后用try/catch包住fetchLater();- 不在
unload/beforeunload里做任何发送动作——这正是本用例要消除的反模式。
八、这份 expectations.md 在仓库流水线中的位置
理解这五条要求的“权威性来源”很重要。按 guides/CONTRIBUTING.md 的定义,每个用例目录必须提供三个核心文件:
| 文件 | 职责 |
|---|---|
guide.md |
面向 AI 编码 Agent 的自包含指导(不含外部链接、注释解释“为什么”、Baseline 兜底宏) |
demo.html |
独立、无控制台警告的参考实现 |
expectations.md |
可观察、可测试的要求清单,下游据此生成自动化 grader |
也就是说,expectations.md 是给机器读的合同,guide.md 是给人/Agent 读的方法论,demo.html 是可运行证据。三者必须互相对齐:guide.md 承诺的每个结果,都要在 expectations.md 里有对应条目,并由 demo.html 实际演示。
这个对齐关系在工具层也有实现:src/core/grader-coverage.ts 的 parseVerifiableExpectations() 会按行解析 expectations.md 的顶层项目符号(并把缩进子项合并进父项),extractTestTitles() 则从 grader.ts 中提取 test('...') 标题,两者用于覆盖率比对;src/grading/generate-grader.ts 展示了下游生成流程会先把 guide.md 做宏展开(replaceMacros(..., { target: 'skills-cli' })),再连同 expectations.md、task.md 一起喂给评测生成器。这也解释了为什么 expectations.md 写成“一条一个可验证断言”的扁平列表最有效——解析器只认顶层的 -/*/数字标记。
另外,src/core/grader-lint.ts 定义了 no-vacuous-boolean-expect、no-tautological-expect、no-test-skip 等规则,防止 grader 用 expect(true) 之类空断言“骗过”覆盖率检查。这与 expectations.md 强调“可观察行为”是同一套设计哲学:只接受能真正失败的断言。
九、落地自检清单
把上面的验收点转成可直接对照的清单:
- 签名:业务代码中每一次发送都是
fetchLater(url, init),url为字符串,init为对象或省略; - 唯一通道:全仓库搜索
sendBeacon(、XMLHttpRequest、new Image()、fetch(ANALYTICS_ENDPOINT,除 polyfill 内部外应无命中; - 单次交付:每次更新数据前先
abort()上一次排期,页面离开后服务端只收到一条最新负载; - 时机:不使用
unload/beforeunload发送,不注册会破坏 bfcache 的监听; - 错误处理:
fetchLater()被try/catch包裹,并对QuotaExceededError、RangeError、TypeError有明确分支或降级; - 体积:payload 保持在 KB 级别,为 64KB/origin 配额留出余量,避免 body 使用
ReadableStream; - 兜底:polyfill 已进入 bundle,且业务代码不直接调用
fetch()/sendBeacon(); - 兼容性声明:用
{{ BASELINE_STATUS("fetchlater") }}这类宏表达 Baseline 状态,不在文档里硬编码兼容性结论。
完成以上各项,你的实现就同时满足了 guides/performance/full-session-analytics/expectations.md 的五条要求,也具备通过 grader.ts 中静态检查与浏览器行为测试双重的条件:静态部分验证“写法正确”,浏览器部分验证“行为正确”——300ms 内不提前发送,可见性变为 hidden 后恰好一次请求。