【用户行为监控】别只做工具人了！手把手带你写一个前端埋点统计 SDK

behavior-monitor/├── dist/                # 打包产物├── src/                 # 源码目录│   ├── index.ts         # 入口文件│   ├── tracker.ts       # 行为采集逻辑（PV/Click/Dwell）│   ├── storage.ts       # 本地存储与 ID 管理 │   └── sender.ts        # 上报逻辑├── test/                # 测试靶场│   ├── server.js        # 本地测试服务│   └── index.html       # 行为触发页面├── package.json         # 项目配置├── rollup.config.js     # Rollup 打包配置├── tsconfig.json        # TypeScript 配置└── README.md

「1.主入口 (index.ts)」

import { trackUserBehavior } from './tracker';import { getUserID, isUVRecorded, setUVRecorded } from './storage';import { sendBehaviorData } from './sender';
export interface InitOptions {  projectName: string;  reportUrl: string;}
export const initUserBehaviorMonitor = (options: InitOptions) => {  const { projectName, reportUrl } = options;  const userId = getUserID();
  // UV 逻辑：如果本地未记录，则上报 UV 并标记  if (!isUVRecorded()) {    sendBehaviorData({      behavior: 'uv',      userId,      projectName,      timestamp: new Date().toISOString()    }, reportUrl);    setUVRecorded();  }
  // 启动行为追踪  trackUserBehavior(projectName, reportUrl);};

export const trackUserBehavior = (projectName: string, reportUrl: string) => {  // 1. 点击监控：通过事件委托监听用户的点击操作  trackClicks(projectName, reportUrl);
  // 2. MPA(传统页面) PV 监控：监听页面首次加载  trackMpaPageView(projectName, reportUrl);
  // 3. 停留时长监控：在页面关闭或隐藏时，计算并上报时长  trackPageDwellTime(projectName, reportUrl);
  // 4. SPA 路由监控：专门处理单页应用的路由跳转  trackSpaBehavior(projectName, reportUrl);};

  const trackMpaPageView = (projectName: string, reportUrl: string) => {    window.addEventListener('load', () => {          // 获取用户id          const userId = getUserID();          // 增加 PV 计数 => (曝光+1)          const pv = incrementPV(); 
          // 发送 PV 数据到服务器          sendBehaviorData({            behavior: 'pv',            userId,            projectName,            timestamp: new Date().toISOString(),            pageUrl: window.location.href,            referrer: document.referrer || '', // 记录来源            pv,          }, reportUrl);          ...    });  };

const trackSpaBehavior = (projectName: string, reportUrl: string) => {  const handleRouteChange = () => {    // 1. 防抖校验：如果 URL 没变（比如 hashchange 和 popstate 同时触发），直接退出    if (window.location.href === lastPageUrl) return;
    // 2. 结算上一页：上报前一个页面的停留时间    reportDwellTime(projectName, reportUrl);
    // 3. 记录当前 URL 为 referrer (在更新 lastPageUrl 之前！)    const referrer = lastPageUrl;
    // 4. 更新状态：保存当前 URL，为下一次跳转做准备    pageLoadTime = Date.now();    lastPageUrl = window.location.href;
    // 5. 记录新页面：上报 PV    const userId = getUserID();    const pv = incrementPV();    sendBehaviorData(      {        behavior: 'pv',        userId,        projectName,        timestamp: new Date().toISOString(),        pageUrl: window.location.href,        referrer: referrer, // 这里的 referrer 是跳转前的页面 URL        pv,      },      reportUrl    );  };
  // 1. 监听 Hash 和浏览器后退/前进  window.addEventListener('hashchange', handleRouteChange);  window.addEventListener('popstate', handleRouteChange);
  // 2. 劫持 History API (解决 pushState/replaceState 不触发事件的问题)  const originalPush = history.pushState;  const originalReplace = history.replaceState;
  // 路由跳转，劫持 pushState  history.pushState = function (...args: Parameters<typeof history.pushState>) {    originalPush.apply(this, args);    handleRouteChange();  };
  // 路由跳转，劫持 replaceState  history.replaceState = function (...args: Parameters<typeof history.replaceState>) {    originalReplace.apply(this, args);    handleRouteChange();  };};

const trackPageDwellTime = (projectName: string, reportUrl: string) => {  // 1. 页面关闭/刷新时  window.addEventListener('beforeunload', () => {    reportDwellTime(projectName, reportUrl);  });
  // 2. 兼容移动端（部分移动端不触发 beforeunload，只触发 pagehide）  window.addEventListener('pagehide', () => {    reportDwellTime(projectName, reportUrl);  });
  // 3. 页面隐藏/切后台时  document.addEventListener('visibilitychange', () => {    if (document.visibilityState === 'hidden') {      reportDwellTime(projectName, reportUrl);    }  });};

// 回顾一下 trackSpaBehavior 里的逻辑const handleRouteChange = () => {  // 1. 路由要变了？先结账！上报停留时长  reportDwellTime(projectName, reportUrl);   // ...};

// 记录上一次上报停留时间的时间戳let lastDwellReportedForLoadTime: number | null = null;
const reportDwellTime = (projectName: string, reportUrl: string) => {  // 防抖：如果当前加载时间段已经上报过，直接跳过  if (lastDwellReportedForLoadTime === pageLoadTime) return;
  // ... 计算并上报 ...
  // 标记已上报  lastDwellReportedForLoadTime = pageLoadTime;};

const trackClicks = (projectName: string, reportUrl: string) => {  document.addEventListener('click', (event) => {    // 只关心那些带 data-track-click 属性的元素    const target = event.target as HTMLElement;    if (target && target.dataset.trackClick) {       // ... 上报 ...    }  });};

<buttondata-track-click="buy_button">购买</button>

/** * @description: 获取用户ID * @return {string} 用户ID */export const getUserID = (): string => {  let userId = localStorage.getItem(USER_ID_KEY);  if (!userId) {    // 给他发个新身份证    userId = generateUUID();    // 存起来，下次就认识了    localStorage.setItem(USER_ID_KEY, userId);  }  return userId;};
/** * @description: 生成唯一标识符 * 简单来说，这就是用来生成一个独一无二的字符串 ID。 * 它通过随机替换模板中的字符来保证唯一性，就像给每个人发一个不重复的号码牌。 * @return {string} 唯一标识符 */ const generateUUID = (): string => {  return 'xxxx-xxxx-4xxx-yxxx-xxxx'.replace(/[xy]/g, (char) => {    const random = (Math.random() * 16) | 0;    const value = char === 'x' ? random : (random & 0x3) | 0x8;    return value.toString(16);  });};

 /* 当天 PV +1 */export const incrementPV = (): number => {  // 获取当天的日期  const today = new Date().toISOString().split('T')[0];  const pvData = localStorage.getItem(`${PV_COUNT_KEY}_${today}`);  const newPV = (pvData ? parseInt(pvData, 10) : 0) + 1;  localStorage.setItem(`${PV_COUNT_KEY}_${today}`, newPV.toString());  return newPV;};

 /* 当前版本：存在即认为已记录 */export const isUVRecorded = (): boolean => {  const today = new Date().toISOString().split('T')[0];  return localStorage.getItem(UV_STORAGE_KEY) === today;};

export const sendBehaviorData = (data: Record<string, any>, url: string) => {  // 1. 包装数据：加上一些公共信息（比如 UserAgent，屏幕分辨率等）  const dataToSend = {    ...data,    userAgent: navigator.userAgent,    // screenWidth: window.screen.width, // 可选  };
  // 2. 优先使用 sendBeacon (最稳，且不阻塞)  // 注意：sendBeacon 不支持自定义 Content-Type，默认是 text/plain  // 这里用 Blob 强制指定为 application/json  if (navigator.sendBeacon) {    const blob = new Blob([JSON.stringify(dataToSend)], {      type: 'application/json',    });
    // sendBeacon 返回 true 表示进入队列成功    navigator.sendBeacon(url, blob);
      return;   }
  // 3. 降级方案：使用 fetch + keepalive  // 即使页面关闭，keepalive 也能保证请求发出  fetch(url, {    method: 'POST',    headers: { 'Content-Type': 'application/json' },    body: JSON.stringify(dataToSend),    keepalive: true, // <--- 关键参数！防止页面关闭时请求被杀  }).catch((err) => {    console.error('上报失败:', err);  });};

{  "name": "behavior-monitor-sdk",  "version": "1.0.0",  "description": "A lightweight front-end behavior monitoring SDK",  "main": "dist/index.cjs.js", // CommonJS 入口  "module": "dist/index.esm.js", // ESM 入口  "browser": "dist/index.umd.js", // UMD 入口  "type": "module",  "scripts": {    "build": "rollup -c",    "dev": "rollup -c -w"  },  "keywords": ["behavior-monitor", "frontend", "sdk"],  "license": "MIT",  "files": ["dist"], // 发布时仅包含 dist 目录  "devDependencies": {    "rollup": "^4.9.0",    "@rollup/plugin-typescript": "^11.1.0",    "@rollup/plugin-terser": "^0.4.0", // 用于压缩代码    "typescript": "^5.3.0",    "tslib": "^2.6.0"  }}

{  "compilerOptions": {    "target": "es5", // 编译成 ES5，兼容旧浏览器    "module": "esnext", // 保留 ES 模块语法，交给 Rollup 处理    "declaration": true, // 生成 .d.ts 类型文件 (关键！)    "declarationDir": "./dist", // 类型文件输出目录    "strict": true, // 开启严格模式，代码更健壮    "moduleResolution": "node" // 按 Node 方式解析模块  },  "include": ["src/**/*"] // 编译 src 下的所有文件}

import typescript from '@rollup/plugin-typescript';import terser from '@rollup/plugin-terser';
export default {  input: 'src/index.ts', // 入口文件  output: [    {      file: 'dist/index.cjs.js',      format: 'cjs',      sourcemap: true,    },    {      file: 'dist/index.esm.js',      format: 'es',      sourcemap: true,    },    {      file: 'dist/index.umd.js',      format: 'umd',      name: 'frontendBehaviorMonitor', // <script> 引入时的全局变量名',      sourcemap: true,      plugins: [terser()], // UMD 格式进行压缩体积    },  ],  plugins: [    typescript({      tsconfig: './tsconfig.json',      declaration: true,      declarationDir: 'dist',    }),  ],};

npm login

npm run build

npm publish --access public

# 请将 behavior-monitor-sdk 替换为你实际发布的包名npm install behavior-monitor-sdk

// 请将 initUserBehaviorMonitor 替换为你实际发布的包名import { initUserBehaviorMonitor } from 'behavior-monitor-sdk';
initUserBehaviorMonitor({  projectName: 'MyMallProject', // 项目名称  reportUrl: 'https://api.yourserver.com/v1/report' // 上报接口地址});

<!-- 请将 behavior-monitor-sdk 替换为你实际发布的包名，x.x.x 替换为具体版本号 --><scriptsrc="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
<script>  // UMD 版本会将 SDK 挂载到 window.frontendBehaviorMonitor  window.frontendBehaviorMonitor.initUserBehaviorMonitor({    projectName: 'MyMallProject',    reportUrl: 'https://api.yourserver.com/v1/report',  });</script>

<!-- 比如：监控购买按钮的点击 --><buttondata-track-click="buy_now_btn">立即购买</button>
<!-- 比如：监控轮播图点击 --><divdata-track-click="banner_ad_01">...</div>