4. 前端埋点代码实现步骤：页面事件、点击事件、曝光事件、自定义属性的代码嵌入

适用场景

本流程适用于采用前端 SDK 进行用户行为数据采集的 Web 或 H5 项目。开发者需根据产品定义的埋点规范，在页面渲染、用户交互、元素可见性等时机嵌入代码，将行为数据发送至数据平台。典型场景包括：

• 统计 PV/UV、页面停留时长、页面跳转路径（页面事件）。
• 记录按钮、链接、卡片等元素的点击频次与转化路径（点击事件）。
• 追踪广告位、推荐模块、弹窗等内容的有效曝光次数与时长（曝光事件）。
• 上传订单金额、商品 ID、用户角色等业务上下文（自定义属性）。

前置条件

序号	条件	说明
1	埋点需求文档已评审	包含事件 ID、属性名、触发时机、采样率等定义。
2	前端与数据平台 SDK 集成完成	SDK 已通过 npm 安装或 script 引入，并初始化 key。
3	开发环境支持调试模式	可启用 SDK 的 log 输出或使用浏览器 Network 面板验证请求。
4	自定义属性 schema 已注册	数据平台已预定义属性的名称、类型、是否必填。

操作步骤

步骤 1：初始化 SDK

在入口文件（如 index.js）中调用初始化方法，传入项目标识与上报地址。

import Analytics from '@datasdk/analytics';

const analytics = new Analytics({
  appKey: 'your_app_key',
  serverUrl: 'https://data.example.com/v1/track',
  isDebug: true    // 开发阶段开启
});

export default analytics;

步骤 2：嵌入页面事件

在路由切换或页面加载完成后的组件内，调用 trackPageView 方法。通常放在 Vue Router 的 afterEach 钩子或 React Router 的 onUpdate 中。

// Vue 3 – router.js
router.afterEach((to, from) => {
  analytics.trackPageView({
    pageName: to.name,
    pageUrl: to.fullPath,
    referrer: from.fullPath
  });
});

参数	类型	说明
pageName	string	页面标识，需与埋点文档一致
pageUrl	string	当前路径
referrer	string	来源页面路径

步骤 3：嵌入点击事件

为需要统计的交互元素绑定点击监听，调用 trackClick 方法。示例监听“立即购买”按钮。

<!-- HTML -->
<button class="buy-now" data-event-id="btn_buy_now">立即购买</button>

<script>
document.querySelector('.buy-now').addEventListener('click', function(e) {
  analytics.trackClick({
    eventId: this.dataset.eventId,
    elementText: this.innerText,
    elementType: 'button'
  });
});
</script>

步骤 4：嵌入曝光事件

利用 IntersectionObserver 检测元素进入可视区域时触发曝光。若 SDK 未内置该功能，可自行封装。

// 工具函数：注册曝光
function registerExposure(element, eventId, extra = {}) {
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        analytics.trackExposure({
          eventId,
          timestamp: Date.now(),
          ...extra
        });
        observer.unobserve(element); // 只曝光一次
      }
    });
  }, { threshold: 0.5 }); // 一半以上可见即算曝光
  observer.observe(element);
}

// 使用示例
registerExposure(
  document.querySelector('.ad-banner'),
  'exp_ad_banner',
  { adId: 'AD001', position: 'top_banner' }
);

参数	说明
threshold	曝光比例阈值，常用 0.5 或 0.8
timestamp	首次进入可视区的时间戳
unobserve	触发一次后断开观察，避免重复上报

步骤 5：添加自定义属性

在触发事件时，将额外业务参数放入 properties 字段。以下示例在购买事件中传递商品信息。

analytics.trackClick({
  eventId: 'btn_buy_now',
  elementText: '立即购买',
  properties: {
    productId: 'P10086',
    price: 299.00,
    userLevel: 'vip',
    paymentMethod: 'wechat'
  }
});

输入输出物

输入	输出
埋点需求文档（含事件 ID、属性定义）	嵌入埋点后的前端代码（git diff）
SDK 初始化配置（appKey, serverUrl）	SDK 调试日志（console 或 Network）
交互元素 DOM 引用或组件引用	数据平台实时事件收据（mock Server 或真实 Trace）

责任边界

• 前端开发：按文档规范嵌入代码，保证触发时机正确，属性拼写无误，处理异常回调。
• 数据产品经理：提供事件定义、属性 schema、采样规则；审批代码中的事件 ID。
• 测试工程师：编写自动化或手动用例，验证所有事件的触发条件、参数、上报次数。
• 后端/平台开发：保证接收接口稳定，返回正确状态码，错误日志可查。

记录材料

• 代码提交记录：每个事件类型的埋点代码应独立 commit，commit message 包含事件 ID。
• 埋点测试报告：含测试环境、用例编号、触发结果、错误摘要。
• 线上监控日志：包括 SDK 错误、上报超时、属性类型不匹配等异常截图。

异常处理

异常现象	可能原因	处理方案
事件未上报，无网络请求	SDK 未初始化、appKey 错误、事件方法未调用	检查初始化代码位置和 isDebug 输出；在控制台手动调用 API 测试
事件重复上报	曝光未正确 unobserve、点击事件绑定了多个监听	单次曝光仅调用一次 trackExposure；使用 removeEventListener 或 single-shot 标识
自定义属性缺失或类型错误	属性键拼写错误、值类型与 schema 不符	对照注册表检查属性名；使用 typeof 校验值；上报前打日志
页面事件在 SPA 路由变化时未触发	路由守卫未绑定 afterEach 或 onUpdate	确认路由库版本；在组件 beforeUnmount 中补偿

验收标准

1. 事件数量准确：在测试场景下，数据平台接收的事件条数与人工观察的操作次数一致（误差 ≤ 2%）。
2. 属性字段完整：所有必填属性均有值，且类型符合 schema（string/number/boolean）。
3. 触发时机正确：页面事件在 URL 变化后 200ms 内触发；点击事件在 click 事件冒泡完成后即刻触发；曝光事件在元素首次进入可视区且超过阈值时触发。
4. 无重复上报：同一元素同一次曝光或点击仅生成一条事件记录（可通过数据平台去重 ID 验证）。
5. 异常处理完备：当网络中断时，SDK 应有重试或本地缓存机制，恢复后补报。