Web Tracking SDK

一个轻量级的前端埋点SDK，专注于页面访问、用户行为和性能数据的采集。支持自动采样、节流控制和SPA应用。

核心功能

1. 自动数据采集

• 🔄 页面访问统计 (PV/UV)

  • 页面进入/离开事件
  • 访客身份识别
  • 访问次数统计
  • 停留时长记录

• 🖱️ 用户交互追踪

  • 按钮点击事件
  • 链接点击事件
  • 页面滚动深度
  • 点击位置热图

• 📊 性能监控

  • 页面加载时间
  • 首次渲染时间
  • DOM就绪时间

2. 智能采集策略

• ⚡ 事件节流 (2秒间隔)
• 🌊 滚动防抖 (500ms)
• 📦 批量数据上报
• 🎯 可配置采样率

安装

npm install @koi-br/web-tracking

快速开始

import { initTracker } from '@koi-br/web-tracking';

const tracker = initTracker({
  appId: 'your-app-id',
  uploadUrl: 'https://your-api.com/collect',
  autoTrack: true,
  uploadInterval: 5000,
  maxCache: 50,
  sampling: {
    ratio: 0.5,                    // 采样率50%
    eventTypes: ['button_click']   // 指定采样事件类型
  }
});

配置项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | - | 应用标识 | | uploadUrl | string | - | 数据上报地址 | | autoTrack | boolean | false | 开启自动采集 | | uploadInterval | number | 5000 | 上报间隔(ms) | | maxCache | number | 50 | 本地缓存上限 | | sampling.ratio | number | 1 | 采样比例(0-1) | | sampling.eventTypes | string[] | - | 采样事件类型 |

采集数据结构

interface TrackEvent {
  // 基础信息
  type: 'page_enter' | 'page_leave' | 'button_click' | 'link_click' | 'page_scroll' | 'uv';
  timestamp: number;
  url: string;
  title: string;

  // 访客信息
  visitorId: string;     // 访客ID
  isNewVisitor: boolean; // 是否新访客
  visitCount: number;    // 访问次数
  sessionId: string;     // 会话ID
  
  // 环境信息
  userAgent: string;     // 浏览器信息
  deviceType: string;    // 设备类型
  screenSize: string;    // 屏幕尺寸
  language: string;      // 用户语言
  timezone: string;      // 时区
  referrer: string;      // 来源页面

  // 交互数据
  duration?: number;     // 停留时长
  scrollDepth?: number;  // 滚动深度
  buttonText?: string;   // 按钮文本
  buttonId?: string;     // 按钮ID
  linkText?: string;     // 链接文本
  linkHref?: string;     // 链接地址
  clickPosition?: {      // 点击位置
    x: number;
    y: number;
    elementPath: string;
  };

  // 性能数据
  performance?: {
    loadTime: number;    // 加载耗时
    firstPaint: number;  // 首次渲染
    domReady: number;    // DOM就绪
  };
}

性能优化

1. 数据采集优化

   • 事件节流控制，避免高频触发
   • 滚动事件防抖处理
   • 可配置采样率，降低数据量

2. 数据上报优化

   • 批量上报机制
   • 本地数据缓存
   • 上报失败自动重试
   • 页面关闭前确保数据发送

浏览器支持

• 支持所有现代浏览器
• 支持移动端浏览器
• 依赖 localStorage 和 Performance API

开发构建

# 安装依赖
npm install

# 开发构建
npm run dev

# 生产构建
npm run build

License

MIT