手动埋点实现原理：在代码中直接插入统计代码

手动埋点，说白了就是写业务代码的时候，顺手把统计代码塞进去。你可能会觉得这有什么好讲的？不就是加几行代码吗？但真踩过坑的人就知道，这里面的门道还真不少。

我以前在一个电商项目里接手过一套手动埋点代码，业务逻辑里散布着几十个 trackEvent 调用，有的在按钮点击里，有的在列表渲染时，还有的在支付回调里。读代码就像在玩“找茬”游戏——你得从一堆业务逻辑里把埋点痕迹挑出来。嗯，那时候我就意识到，手动埋点虽然直观，但如果不按套路来，后期维护就是灾难。

核心原理：埋点本质上就是“偷听”用户操作

为什么这么说？你想一下，用户点击按钮、滚动页面、提交表单——这些都是用户和页面交互的动作。我们想要把这些行为数据“偷”回来，最直接的方式就是在动作发生的地方，塞一个上报函数。比如：

// 典型的埋点代码
document.getElementById('buyBtn').addEventListener('click', function() {
  // 业务逻辑
  addToCart(productId);
  // 埋点逻辑
  trackEvent('click_buy', { productId, userId, timestamp: Date.now() });
});

这里 trackEvent 就是埋点函数，负责把数据拼好、发到服务器。整个过程分三步：

1. 定位：找到要监听的操作节点或时机（比如点击、表单提交、组件挂载）。
2. 拼参数：把产品ID、用户ID、时间戳等关键信息组装好。
3. 发送：通常用 navigator.sendBeacon 或 new Image() 打点，防阻塞。

常见的手动埋点场景

我总结了几种最常动手写埋点的场景，每个都附一段实际代码走法。

1. 点击事件埋点

// HTML
<button onclick="handleBuy()" data-product="1001">立即购买</button>

// JS
function handleBuy() {
  // 业务
  doBuy();
  // 埋点
  let productId = event.target.getAttribute('data-product');
  track('click_buy', { productId });
}

2. 页面曝光埋点

曝光埋点经常被忽略——用户看到了某个模块，但没点击。这个在首页 banner、推荐列表里特别重要。我一般用 IntersectionObserver 实现：

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      track('exposure', { module: entry.target.id });
      observer.unobserve(entry.target); // 只上报一次
    }
  });
}, { threshold: 0.5 });

document.querySelectorAll('[data-exposure]').forEach(el => observer.observe(el));

3. 页面停留时长埋点

这个稍微绕一点。我通常在 SPA 的路由离开时，算一下进入时间。如果不用框架，就监听 visibilitychange 事件：

let enterTime = Date.now();
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    track('page_duration', { ms: Date.now() - enterTime });
  }
});

手动埋点的大分类

我把手动埋点按照插入位置分了三类，说白了就是：

• 侵入式埋点：写在事件回调里，跟业务代码混在一起。缺点很明显——以后想统一改埋点名称，得满文件找。
• 声明式埋点：通过 data-track 属性声明，然后用全局监听器统一处理。这样埋点和业务分离了一些，但属性值多了依然难维护。
• 无侵入式埋点（其实是 AOP 的思路，这里先不展开）：通过代理函数或装饰器自动拦截。严格来说不算纯手动，但部分项目会用。

手动埋点的典型难＞点

我在团队里做过几次埋点治理，总结了三个高频问题：

1. 埋点与业务耦合：删业务逻辑时忘了删埋点，导致后台多出大量无意义数据。我建议每个埋点调用后面加个注释，比如 // [埋点] 购买按钮点击，方便批量搜索。
2. 参数不一致：不同人用不同字段名，比如 productId 有的人写 pid，后端解析时一头雾水。归档一个全局常量表很有必要。
3. 重复埋点：组件复用时，不小心把埋点绑了多层，一条点击发了十几遍数据。加个防重判断能省很多清洗时间。