Track Analytics

一个支持Web和移动端H5的埋点SDK。提供自动和手动埋点功能，可以收集用户行为、性能数据、错误信息等。

特点

• 支持 Web 和移动端 H5
• 插件化架构，易于扩展
• 自动捕获页面访问、停留时间、点击行为
• 自动监控页面性能和错误
• 支持自定义事件埋点
• 支持离线缓存和批量上报
• 体积小，无外部依赖

安装

npm install track-analytics --save

快速开始

基础使用

import createTracker from 'track-analytics';

// 初始化
const tracker = createTracker({
  appId: 'your-app-id',
  reportUrl: 'https://your-api.com/collect'
});

// 使用
tracker.track('button_click', { buttonName: '登录按钮' });

设置用户信息

tracker.setUser({
  userId: '123456',
  userName: 'test_user',
  userRole: 'member'
});

添加自定义参数

tracker.setCustomParams({
  version: '1.0.0',
  channel: 'app_store'
});

配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | 必填 | 应用标识 | | reportUrl | string | 必填 | 数据上报地址 | | debug | boolean | false | 是否开启调试模式 | | reportStrategy | 'immediate' | 'batch' | 'batch' | 上报策略: 立即上报或批量上报 | | reportInterval | number | 5000 | 批量上报时间间隔(ms) | | autoTrackPV | boolean | true | 是否自动上报PV | | autoTrackStayTime | boolean | true | 是否自动上报页面停留时长 | | autoTrackClick | boolean | false | 是否自动上报点击事件 | | autoTrackError | boolean | true | 是否自动上报错误 | | autoTrackPerformance | boolean | true | 是否自动上报性能 |

自动埋点

SDK默认开启以下自动埋点功能：

• PV埋点：页面访问量统计
• 页面停留时间：统计用户在页面停留的时间
• 错误监控：捕获JS运行时错误、Promise未处理的拒绝、资源加载错误
• 性能监控：采集页面加载性能、资源加载情况、关键渲染指标

可以通过配置项开启自动点击埋点：

const tracker = createTracker({
  appId: 'your-app-id',
  reportUrl: 'https://your-api.com/collect',
  autoTrackClick: true
});

手动埋点

追踪自定义事件

// 基础事件埋点
tracker.track('search', { keyword: '埋点' });

// 带更多信息的事件埋点
tracker.track('product_view', {
  productId: '10001',
  productName: '商品名称',
  price: 99.9,
  category: '电子产品'
});

手动追踪PV

// 手动触发PV埋点，可以传递额外参数
tracker.trackPageView({ 
  pageType: 'detail',
  source: 'recommend'
});

手动追踪错误

try {
  // 业务代码
} catch (error) {
  // 手动上报错误
  tracker.trackError(error, { 
    position: 'payment-module',
    fatal: true
  });
}

自定义埋点元素

在HTML元素上添加data-track-xxx属性，自动埋点时会采集这些属性：

<button 
  data-track-id="login_btn"
  data-track-category="user"
  data-track-action="click"
>
  登录
</button>

插件系统

SDK使用插件系统扩展功能。可以创建自定义插件：

import { Plugin } from 'track-analytics';

// 创建自定义插件
class MyCustomPlugin implements Plugin {
  name = 'my-custom-plugin';
  
  install(sdk) {
    // 插件实现逻辑
    console.log('插件已安装');
    
    // 可以访问sdk实例
    sdk.track('plugin_installed', { name: this.name });
  }
  
  destroy() {
    // 清理逻辑
    console.log('插件已卸载');
  }
}

// 使用自定义插件
tracker.use(new MyCustomPlugin());

浏览器兼容性

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 16+
• iOS Safari 11+
• Android Browser 4.4+

许可证

MIT