[!info] related notes

• 所属 MOC: 前端工程化 MOC
• 前置概念: 埋点, 埋点事件模型
• 并列概念: 埋点数据质量与治理, Fetch API
• 易混淆概念: 性能监控体系
• 关系笔记: 前端埋点工程化

前端埋点 SDK

一句话定义

前端埋点 SDK 是事件采集链路的运行时基础设施，负责把业务层调用转成可可靠上报的结构化事件。

核心模块

• 初始化：读取配置、环境、版本、用户身份
• normalize：标准化事件结构
• enrich：补全页面、设备、实验、会话等上下文
• validate：做 schema 和字段校验
• queue：写入内存队列，必要时落盘
• transport：批量上报，常见方式包括 sendBeacon、fetch keepalive
• retry：失败重试、离线补发、页面隐藏时强制 flush

为什么需要队列

• 浏览器环境不可靠，用户可能随时刷新、关闭、断网、切后台
• 如果每次 track() 都直接 fetch，很容易丢数据，也会制造过多请求
• 更现实的目标通常是“尽量不丢、允许重复、服务端去重”，而不是追求前端侧的 exactly-once

常见增强能力

• 采样
• 限流
• 去重
• 调试模式
• 隐私开关
• 插件系统
• 多端环境兼容

边界与易混淆点

• SDK 提供的是能力，不等于事件语义本身，业务语义仍然应该由业务层决定
• 埋点 SDK 可以和 RUM、错误监控共用上报链路，但它们的目标不完全相同

Related notes

• 前端工程化MOC
• 前端埋点工程化
• 埋点事件模型
• 曝光埋点