前端埋点 SDK

这是一个用于实现前端埋点功能的SDK。统计用户在web应用中的行为数据，包括页面访问(PV)、独立访客(UV)、点击、滚动、停留时间等。

功能特性

• 📊 自动采集页面访问数据（PV）
• 👤 独立访客统计（UV）
• 🖱️ 点击事件追踪
• 📜 页面滚动行为统计
• ⏱️ 页面停留时间统计
• 🔄 自定义事件上报
• 💾 数据本地缓存
• 🚀 自动批量上报
• 🔗 支持单页面应用（SPA）
• 🆔 访客身份持久化

目录结构

web-tracking/
├── README.md
├── package.json
├── tsconfig.json
├── rollup.config.js
├── src/
│   ├── index.ts
│   ├── core/
│   │   ├── tracker.ts
│   │   ├── collector.ts
│   │   └── reporter.ts
│   ├── utils/
│   │   └── visitor-id.ts
│   └── types/
│       └── index.ts
└── dist/
    ├── index.js
    ├── index.es.js
    └── index.d.ts

安装

npm install @koi-br/web-tracking

使用方法

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

// 初始化
const tracker = initTracker({
  appId: 'your-app-id',
  uploadUrl: 'https://your-server.com/collect',
  autoTrack: true,
  uploadInterval: 5000
});

// 手动上报事件
// 手动上报自定义事件
// eventId: 事件标识,可以是任意字符串
// properties: 事件属性,可以包含任意自定义信息
tracker.track('custom_event', {
  eventType: 'click',      // 事件类型
  elementId: 'submit-button',  // 元素ID
  // 可以添加更多自定义属性...
  price: 99,
  productId: 'p001',
  category: 'electronics'
});

// 也可以这样使用
tracker.track('purchase', {
  orderId: 'ORDER_123',
  amount: 199.99,
  currency: 'CNY'
});

配置项

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appId | string | 是 | 应用唯一标识 | | uploadUrl | string | 是 | 数据上报地址 | | autoTrack | boolean | 否 | 是否自动采集行为数据 | | uploadInterval | number | 否 | 上报间隔(ms) | | maxCache | number | 否 | 最大缓存事件数 |

数据采集说明

PV（页面访问量）

• 自动采集每个页面的访问数据
• 支持单页面应用（SPA）路由变化的 PV 统计
• 采集数据包含：页面标题、URL、访问时间、会话ID等

UV（独立访客）

• 通过本地存储生成并维护访客ID
• 访客ID默认有效期为365天
• 支持跨会话的用户识别

页面停留时间

• 记录用户进入和离开页面的时间
• 自动计算页面停留时长
• 支持页面关闭前的数据上报

事件数据结构

interface TrackEvent {
  eventId: string;        // 事件标识
  eventType: string;      // 事件类型
  timestamp: number;      // 事件时间戳
  properties: {
    visitorId: string;    // 访客ID
    sessionId: string;    // 会话ID
    // ... 其他属性
  };
}

开发构建

# 安装依赖
npm install

# 开发构建
npm run dev

# 生产构建
npm run build

# 生成类型文件
npm run types

数据统计示例

// 后端统计示例（伪代码）

// UV统计
SELECT COUNT(DISTINCT properties->>'visitorId') as uv
FROM tracking_events
WHERE eventId = 'page_view'
  AND timestamp BETWEEN :start_date AND :end_date;

// PV统计
SELECT COUNT(*) as pv
FROM tracking_events
WHERE eventId = 'page_view'
  AND timestamp BETWEEN :start_date AND :end_date;

License

MIT