Track SDK

一个轻量级、可扩展的前端埋点采集 SDK，支持自动/手动事件追踪、页面访问、用户标识、地理位置等功能，目前只适用于 Web 场景。

特性

• 自动/手动页面访问追踪
• 自定义事件采集
• 用户 ID 设置与切换
• 支持 SPA 路由监听
• 可选地理位置采集
• 设备信息自动采集
• 支持自定义上报端点

安装

pnpm add track-sdk
# 或
npm install track-sdk

快速上手

import trackEvent from 'track-sdk';

const tracker = trackEvent.init({
  appId: '你的应用ID',
  endpoint: 'https://your-server.com/track',
  debug: true, // 开启调试日志
  autoTrackPageView: true, // 自动追踪页面访问
  enableLocation: false, // 是否采集地理位置
});

// 手动追踪事件
tracker.track('button_click', { buttonId: 'submitBtn' });

// 设置用户ID
tracker.setUserId('user_123');

// 设置页面信息（适用于SPA）
tracker.setPageInfo({
  title: '用户中心',
  url: '/user/profile',
});

配置项（SDKConfig）

| 字段 | 类型 | 说明 | |---------------------|-----------|----------------------------| | appId | string | 应用唯一标识（必填） | | endpoint | string | 事件上报地址（可选） | | userId | string | 用户ID（可选） | | autoTrackPageView | boolean | 自动追踪页面访问（默认true）| | useBeacon | boolean | 是否使用Beacon上报（默认true）| | flushInterval | number | 定时上报间隔（毫秒，默认30000。<=0 关闭）| | maxBatchSize | number | 事件累计到该数量立即上报（默认20）| | enableLocation | boolean | 是否采集地理位置（默认false）| | debug | boolean | 是否输出调试日志（默认false）|

主要API

初始化与配置

// 初始化SDK
const tracker = trackEvent.init({
  appId: '你的应用ID',
  endpoint: 'https://your-server.com/track',
  debug: true,
  autoTrackPageView: true,
  enableLocation: false,
});

// 动态更新配置
tracker.updateConfig({
  debug: true,
  enableLocation: true,
});

事件追踪

// 追踪自定义事件
tracker.track('button_click', { 
  buttonId: 'submitBtn',
  buttonText: '提交'
});

// 手动追踪页面访问
tracker.trackPageView({
  pageType: 'product_detail',
  productId: '123'
});

用户与页面信息

// 设置/切换用户ID
tracker.setUserId('user_123');

// 手动设置页面信息（适用于SPA）
tracker.setPageInfo({
  title: '用户中心',
  url: '/user/profile',
  referrer: '/home'
});

事件监听

SDK 提供了以下事件供监听：

// 监听事件收集
tracker.eventEmitter.on('event', (event) => {
  console.log('新事件已添加', event);
});

// 监听页面访问
tracker.eventEmitter.on('pageView', (pageInfo, properties) => {
  console.log('页面访问', pageInfo, properties);
});

// 监听用户ID变更
tracker.eventEmitter.on('userIdChanged', (userId) => {
  console.log('用户ID已变更', userId);
});

// 监听页面信息变更
tracker.eventEmitter.on('pageInfoChanged', (pageInfo) => {
  console.log('页面信息已变更', pageInfo);
});

// 监听数据发送成功
tracker.eventEmitter.on('sendSuccess', (trackEvent) => {
  console.log('数据发送成功', trackEvent);
});

// 监听数据发送失败
tracker.eventEmitter.on('sendError', (error, trackEvent) => {
  console.log('数据发送失败', error, trackEvent);
});

服务端接收参数

服务端将接收到以下格式的数据：

interface SDKTrackEvent {
  /** 会话ID */
  sessionId: string;

  /** 用户ID */
  userId?: string;

  /** 平台ID */
  platform: string;

  /** 设备信息 */
  deviceInfo: {
    deviceId?: string;      // 设备编号
    deviceModel?: string;   // 设备型号
    osVersion?: string;     // 操作系统版本
    screenWidth: number;    // 屏幕宽度
    screenHeight: number;   // 屏幕高度
  };

  /** 位置信息 */
  locationInfo?: {
    longitude: number;      // 经度
    latitude: number;       // 纬度
  };

  /** 事件列表 */
  events: Array<{
    eventName: string;      // 事件名称
    properties?: Record<string, any>;  // 事件属性
    pageInfo: {
      url: string;          // 页面URL
      title: string;        // 页面标题
      referrer?: string;    // 来源URL
    };
    occurTime: number;      // 发生时间
  }>;
}

数据上报策略

• 页面隐藏/卸载时：visibilitychange(hidden)、pagehide、beforeunload 触发上报

• 网络恢复时：监听 online 事件立即尝试上报未发送数据

• 定时上报：通过 flushInterval 配置（默认30s）周期性发送队列数据

• 批量阈值：maxBatchSize（默认20）达到后立刻上报，减少延迟