在上一家公司做埋点业务开发时，我遇到过一个非常典型的前端埋点实现：项目里封装了一个基于 img 标签的上报方法，需要埋点时由业务侧自己调用这个方法，按具体场景绑定事件、组织参数并触发发送。

这种方式很常见。它利用浏览器加载图片不受常规 Ajax 跨域限制的特点，把埋点参数拼到图片 URL 后面，然后通过一个统一方法创建图片请求。简化后大概是这样：

function sendTrackByImg(params) {
  const query = new URLSearchParams(params).toString();
  const img = new Image();
  img.src = `https://track.example.com/pixel?${query}`;
}

从“能不能发出去”这个角度看，这个方案确实简单直接，也能绕开一些跨域问题。它也不是完全没有封装，至少把底层发送动作收敛到了一个方法里。但随着业务规模变大，它的问题会越来越明显。尤其是在点击埋点、曝光埋点、页面停留时长、首屏渲染、自定义事件等场景逐渐增多之后，原来的方案很快就暴露出复用性、可靠性和性能三个方面的短板。

react-track-hooks 就是在这个背景下诞生的。它不是为了做一个大而全的数据分析平台，而是为了解决前端埋点采集层的工程化问题：让埋点代码更好复用，让数据发送更可靠，让网络请求对页面性能的影响更可控。

1. 原来的 img 埋点方案有什么问题

用 img 标签做埋点，最大的优点是简单。即使项目里已经封装了一个发送方法，这个方法通常也只解决“怎么把数据发出去”，并没有解决“什么时候触发、如何绑定事件、不同场景如何复用、失败后如何处理”这些更上层的问题。

首先是代码复用问题。

不同类型的埋点有不同的触发方式。点击埋点依赖用户点击事件，曝光埋点依赖元素是否进入视口，页面停留埋点依赖页面生命周期和用户活跃状态，自定义埋点依赖具体业务流程。

原来的封装只是一个通用发送函数。真正使用时，每个业务组件仍然要自己处理事件绑定、参数组织、触发时机和异常边界。点击按钮要自己绑定 onClick，列表曝光要自己监听滚动或判断元素位置，页面停留要自己记录进入和离开时间，自定义事件也要自己决定什么时候调用发送方法。久而久之，发送方法虽然复用了，但场景能力没有复用，埋点逻辑仍然会散落在业务代码里。

其次是可靠性问题。

img 请求通常是“发出去就不管了”。请求是否真的到达服务端、服务端是否成功处理、网络是否失败，前端很难形成完整闭环。即使监听 onerror，实际项目里也很少有统一的失败缓存和重试机制。

这意味着只要请求失败，这条埋点数据就直接丢失了。对于普通日志可能还可以接受，但对转化链路、关键按钮、曝光数据、页面停留等核心分析指标来说，这种丢失会影响后续的数据判断。

第三是性能问题。

原方案里每一条埋点都发起一次请求。页面首屏渲染时，经常会有几十个曝光埋点同时触发，浏览器网络面板里瞬间出现大量埋点请求。

这些请求虽然单个体积不大，但它们和核心业务接口共享浏览器请求资源。尤其在弱网、移动端或者首屏资源紧张的场景下，大量低优先级埋点请求可能会和关键业务请求竞争，拖慢首屏渲染和交互响应。

这里还有一个很现实的浏览器限制：在常见的 Chrome 场景下，HTTP/1.1 对同一域名的并发连接数通常是 6 个左右。也就是说，如果首屏同时打出几十个埋点请求，它们并不会真正无限并发，而是会排队争抢有限连接。即使在 HTTP/2 多路复用下，不再是简单的 6 连接模型，大量请求仍然会占用带宽、调度队列和服务端处理资源。对埋点这种低优先级请求来说，最理想的状态应该是减少请求数量，并尽量不要阻塞核心业务接口。

所以问题可以总结为三点：

• 复用性差：点击、曝光、页面停留等能力每次都要重复实现。
• 可靠性弱：缺少失败缓存、失败重试，请求失败后数据直接丢失。
• 性能不可控：每条埋点单独请求，首屏大量埋点会影响核心业务请求。

2. react-track-hooks 的设计目标

基于这些问题，我开发了 react-track-hooks。它的目标很明确：围绕前端埋点采集层，从复用性、可靠性和性能三个方向做优化。

第一，复用性上，把常见埋点场景封装成 React Hooks。业务组件不再关心底层如何发送，只需要选择对应的 Hook。

第二，可靠性上，增加失败缓存和重试机制。请求失败后不再直接丢弃，而是存入本地失败队列，在合适时机自动重试。

第三，性能上，支持批量上报。多个埋点事件可以先进入内存队列，再按数量或时间窗口统一发送，减少请求数量，降低对首屏核心请求的干扰。

这三个方向对应的不是单点优化，而是把原本零散的埋点代码升级成一个轻量 SDK。

3. 复用性优化：用 Hooks 抽象埋点场景

在 React 项目中，用户行为和组件生命周期天然适合用 Hook 封装。react-track-hooks 把常见埋点能力拆成了多个场景 Hook。

点击埋点使用 useTrackClick：

const handleClick = useTrackClick('button_click', {
  page: 'home',
  module: 'banner',
});

return <button onClick={handleClick}>立即体验</button>;

曝光埋点使用 useTrackExposure：

const exposureRef = useTrackExposure<HTMLDivElement>('card_exposure', {
  cardId: 'card_001',
});

return <div ref={exposureRef}>推荐卡片</div>;

页面停留使用 useTrackPageStay：

useTrackPageStay('article_page_stay', {
  articleId,
});

自定义事件使用 useTrackCustom：

const trackSubmit = useTrackCustom('form_submit', {
  formName: 'login',
});

trackSubmit({ result: 'success' });

这些 Hook 的底层都会复用统一的 useTrack。也就是说，业务侧看到的是不同场景的 API，SDK 内部则使用统一的数据结构、统一的配置和统一的发送链路。

这样做带来的收益很明显。

业务组件不再只是调用一个底层发送函数，也不需要在每个场景里重复处理事件绑定和触发条件。点击怎么采集、曝光怎么判断、页面停留怎么结算，都沉到 SDK 内部。业务代码只需要声明“这里要上报什么事件”。

4. 曝光埋点：从组件渲染升级为真实可见

原来的曝光埋点很容易被写成“组件渲染就上报”。但组件渲染不等于用户看见。比如信息流页面一次性渲染了很多卡片，首屏以下的卡片虽然在 DOM 中，但用户根本没有滚动到那里。

react-track-hooks 的曝光埋点基于 IntersectionObserver 实现。它会监听目标元素和视口的交叉状态，只有元素达到指定可见比例时才触发曝光。

默认配置中，曝光阈值是 0.5，也就是元素可见面积达到 50% 时才算曝光。同时还支持 exposureOnce，可以控制同一个元素是否只曝光一次。

这比简单的 mounted 上报更准确，也比业务组件手动监听滚动和计算元素位置更稳定。

5. 页面停留：从在线时长升级为活跃停留

页面停留时长也是一个容易被误算的指标。如果只用进入页面和离开页面的时间差，用户切到后台、长时间不操作、电脑休眠等情况都会被算进停留时间。

useTrackPageStay 的设计是统计“活跃停留时长”。它会监听鼠标、滚动、键盘、触屏等用户活跃行为，并记录最后一次活跃时间。同时，它会监听页面显隐变化，在页面隐藏时立即结算当前停留片段。

它还提供了几个配置：

• timeout：用户多久不操作后暂停计时。
• minDuration：低于多少时长不上报，过滤无效停留。
• maxDuration：限制最长单次停留，避免异常数据。
• checkInterval：周期性检查用户是否不活跃。

通过这些机制，页面停留不再是粗糙的“页面开了多久”，而是更接近“用户实际参与了多久”。

6. 可靠性优化：失败缓存与自动重试

原来的 img 埋点方案最大的问题之一，是失败后没有补偿。网络异常、接口异常、页面关闭时机不稳定，都可能导致数据丢失。

react-track-hooks 在发送失败时，会把失败事件写入 localStorage.failedTracks。每条失败数据会记录事件信息、重试时间和重试次数。

随后，SDK 会在多个时机自动触发重试：

• 首屏渲染完成后延迟重试一次。
• 页面从隐藏重新变为可见时重试。
• 浏览器空闲时周期性检查失败队列。
• 新埋点成功发送后，顺带尝试补偿失败队列。

重试策略使用指数退避。也就是说，失败事件不会被无限高频重试，而是根据初始延迟和退避倍率逐步拉长间隔，并受最大重试次数限制。

这套机制让埋点发送从“发完就丢”变成了“失败可缓存、后续可补偿”。对于关键路径数据来说，这个差异非常重要。

7. 性能优化：批量上报降低请求压力

在首屏场景下，埋点请求数量往往非常可观。尤其是首页、推荐流、商品列表、看板页面等，一次渲染可能触发几十条曝光埋点。

如果每条埋点都独立发请求，那么网络层会出现大量低价值请求。这些请求虽然不直接影响业务结果，但会占用浏览器连接、网络带宽和服务端接收能力。

除了减少请求数量，我还希望降低埋点补偿逻辑对主流程的干扰。因此在失败重试和补偿上报的调度上，react-track-hooks 使用了 requestIdleCallback。它会尽量把失败队列的重试放到浏览器空闲时执行，而不是在首屏渲染和核心业务请求最繁忙的时候抢占资源。

例如，单条或批量埋点上报成功后，SDK 不会立刻同步处理失败队列，而是优先尝试在空闲时间触发：

if (window.requestIdleCallback) {
  window.requestIdleCallback(() => retryFailedTracks(), { timeout: 2000 });
} else {
  setTimeout(() => retryFailedTracks(), 1000);
}

全局失败重试监听中也使用了类似策略：当浏览器支持 requestIdleCallback 时，失败队列会在空闲阶段周期性检查；不支持时再退化为普通定时器。这样做的目标不是让所有埋点请求都延后，而是把“失败补偿”这类非核心链路放到更低优先级的位置，尽量减少对首屏渲染和核心接口的影响。

react-track-hooks 支持批量上报。开启批量模式后，埋点事件不会立刻发送，而是先进入内存队列。队列满足以下条件之一时触发上报：

• 队列长度达到 batchSize。
• 等待时间达到 batchInterval。
• 页面隐藏时触发队列 flush。

批量上报会把多条事件合并成一次请求：

{
  "tracks": [
    { "eventName": "card_exposure", "type": "exposure" },
    { "eventName": "button_click", "type": "click" }
  ]
}

这样可以显著减少请求数量。原本首屏几十个独立请求，可以变成几次批量请求，减少对核心业务接口的干扰。

8. 为什么没有继续使用 img 方案

img 方案绕开跨域很方便，但它本质上是把埋点请求伪装成资源加载。这个方案适合非常简单的打点，但不适合复杂业务场景下的埋点 SDK。

现代项目更推荐使用明确的 API 接口来接收埋点数据，比如 /api/track 和 /api/track/batch。跨域问题可以通过服务端 CORS、同域代理、网关转发或 Next.js Route Handler 解决，而不应该长期依赖图片请求规避。

更重要的是，使用 fetch 后，前端可以拿到响应状态，可以判断失败，可以写入缓存，可以做重试，也可以支持批量 JSON 数据。这些能力都是 img 方案很难优雅实现的。

所以 react-track-hooks 的方向不是继续包装 img，而是把埋点上报升级成明确、可控、可维护的请求链路。

9. 架构设计

整个 SDK 的运行链路如下。不同场景 Hook 最终汇入统一发送入口，再根据配置进入单条上报或批量队列；失败数据则写入本地队列，并在页面恢复、浏览器空闲或后续请求成功时重试。

图中页面离开相关逻辑主要依赖 visibilitychange：批量队列在页面进入 hidden 状态时 flush，stay 埋点则在 hidden 时强制使用单条请求上报。当前实现没有使用 beforeunload、pagehide、unload 或 navigator.sendBeacon，实际请求使用的是开启 keepalive 的 fetch。

从代码组织上看，react-track-hooks 的整体结构比较轻量，但分层清晰。

src
├── index.ts                         # 对外统一出口
├── types.ts                         # 埋点类型和配置类型
├── utils.ts                         # 环境判断、本地存储、事件 ID 等工具
└── track
    ├── config.ts                    # 全局配置单例
    ├── core
    │   ├── sendTrack.ts             # 单条发送入口，决定单发或入批量队列
    │   ├── sendBatchTrack.ts        # 批量队列、定时上报、页面隐藏 flush
    │   └── retryTrack.ts            # 失败缓存和重试机制
    ├── hooks
    │   ├── useTrack.ts              # 基础埋点 Hook
    │   ├── useTrackClick.ts         # 点击埋点
    │   ├── useTrackExposure.ts      # 曝光埋点
    │   ├── useTrackPageStay.ts      # 页面停留埋点
    │   ├── useTrackFirstRender.ts   # 首次渲染埋点
    │   ├── useTrackCustom.ts        # 自定义埋点
    │   └── useTrackInit.ts          # 初始化配置、批量上报和重试监听
    └── listeners
        └── useTrackRetryListener.ts # 全局失败重试监听

这套结构对应了三层职责：

• hooks 负责场景抽象，让业务代码更易复用。
• core 负责发送、批量、失败缓存和重试。
• config 和 listeners 负责全局配置与生命周期监听。

业务组件不直接接触 sendTrack、localStorage 或批量队列，而是通过 Hook 表达埋点意图。底层的可靠性和性能策略则由 SDK 统一管理。

10. 初始化方式

使用方可以在应用入口调用 useTrackInit 完成初始化：

import { useTrackInit } from 'react-track-hooks';

function TrackProvider() {
  useTrackInit({
    trackUrl: '/api/track',
    batchTrackUrl: '/api/track/batch',
    enable: true,
    enableBatch: true,
    retryConfig: {
      maxRetryTimes: 3,
      initialDelay: 1000,
      delayMultiplier: 2,
    },
    batchConfig: {
      batchSize: 10,
      batchInterval: 5000,
    },
    exposureConfig: {
      exposureOnce: true,
      exposureThreshold: 0.5,
    },
    pageStayConfig: {
      timeout: 30 * 60 * 1000,
      minDuration: 2000,
      maxDuration: 60 * 60 * 1000,
      checkInterval: 1000,
    },
  });

  return null;
}

初始化后，业务组件就可以在各自场景里使用对应 Hook。这样埋点能力既有统一配置，又能在单个 Hook 中局部覆盖。

11. 从业务问题到 SDK 的价值

回到最开始的问题，react-track-hooks 解决的是一个很具体的工程痛点。

原来的 img 埋点方式，短期看实现成本低，长期看维护成本高。虽然它封装了底层发送方法，但每个业务组件仍然要自己处理点击、曝光、停留等场景逻辑，缺少统一的场景抽象；它缺少失败缓存和重试，让关键数据容易丢失；它让每条埋点都发请求，首屏大量低优先级请求会影响核心体验。

react-track-hooks 则从三个方向进行了重构：

• 用 Hooks 提升复用性，把点击、曝光、停留、自定义事件封装成统一能力。
• 用失败缓存和重试机制提升可靠性，让请求失败后仍然有补偿机会。
• 用批量上报和 requestIdleCallback 空闲调度提升性能表现，减少高频埋点和失败补偿对首屏及业务接口的影响。

它不是为了追求复杂，而是把埋点这件事从“散落在业务代码里的临时逻辑”变成了“可配置、可复用、可补偿、可演进的前端基础设施”。

12. 总结

react-track-hooks 的开发动机来自真实业务中的埋点痛点：img 请求方案虽然简单，但在复用性、可靠性和性能上都有明显缺陷。

通过 Hook 化的场景封装、统一的发送链路、失败缓存与指数退避重试、批量上报、requestIdleCallback 空闲调度和页面生命周期处理，react-track-hooks 将前端埋点从一次性的请求拼接，升级成了一套轻量可靠的 React 埋点 SDK。

如果用一句话概括这个项目：react-track-hooks 是一次从“能发出去就行”的埋点实现，到“可维护、可重试、低干扰”的前端埋点工程化方案的演进。