analytics-tracker-sdk v1.0.0

Analytics Tracker SDK

一个功能强大的前端数据埋点 SDK，支持自动埋点、手动埋点、性能监控、错误监控等特性。

功能特性

• 🚀 自动埋点

  • 页面访问（PV）自动采集
  • 用户点击行为自动采集
  • 支持采样率配置

• 📊 性能监控

  • FCP (First Contentful Paint)
  • LCP (Largest Contentful Paint)
  • FID (First Input Delay)
  • CLS (Cumulative Layout Shift)
  • 页面加载时间
  • DOM 解析时间
  • 自动采集和上报性能指标
  • 支持自定义性能指标

• 🔍 错误监控

  • JS 运行时错误捕获
  • Promise 未处理异常监控
  • 资源加载错误监控
  • AJAX 请求异常监控
  • 错误堆栈信息采集
  • 错误上下文信息收集

• 💡 其他特性

  • 数据批量上报
  • 自定义事件上报
  • 用户信息管理
  • 调试模式支持
  • 离线数据存储
  • 自动重试机制

安装

npm install analytics-tracker-sdk
# 或
yarn add analytics-tracker-sdk

快速开始

import { createTracker } from 'analytics-tracker-sdk';

// 创建 tracker 实例
const tracker = createTracker();

// 初始化配置
tracker.init({
  reportUrl: 'https://your-api.com/collect',
  appId: 'your-app-id',
  // 可选配置
  autoTrackPageView: true,
  autoTrackClick: true,
  autoTrackPerformance: true,
  autoTrackError: true,
  batchSize: 10,
  reportInterval: 5000,
  debug: false,
  samplingRate: 1
});

// 手动上报事件
tracker.track('custom_event', {
  action: 'click',
  target: 'submit_button'
});

// 设置用户信息
tracker.setUser({
  userId: '12345',
  userType: 'vip'
});

// 销毁实例
tracker.destroy();

API 文档

createTracker()

创建一个新的 tracker 实例。

tracker.init(config)

初始化 tracker，配置选项：

错误监控

错误监控模块自动捕获以下类型的错误：

1. 运行时错误

   • JS 语法错误
   • 类型错误
   • 引用错误等

2. Promise 异常

   • 未捕获的 Promise rejection
   • async/await 异常

3. 资源加载错误

   • 图片加载失败
   • 脚本加载失败
   • CSS 文件加载失败

4. AJAX 请求错误

   • 请求超时
   • 网络错误
   • 服务器错误

错误信息包含：

• 错误类型
• 错误信息
• 错误堆栈
• 发生时间
• 错误来源

性能监控

性能监控模块自动收集以下指标：

1. 页面加载性能

   • 页面完全加载时间
   • DOM 内容加载时间
   • DOM 可交互时间

2. Web Vitals 指标

   • LCP：最大内容渲染时间
   • FID：首次输入延迟
   • CLS：累积布局偏移

性能数据包含：

• 指标类型
• 指标值
• 采集时间戳

测试覆盖率

本项目采用 Jest 进行单元测试，当前测试覆盖率达到 100%：

• 语句覆盖率：100%
• 分支覆盖率：100%
• 函数覆盖率：100%
• 行覆盖率：100%

测试用例覆盖以下核心功能：

1. 错误监控

   • 运行时错误捕获
   • Promise 异常处理
   • 资源加载错误
   • 错误上报机制

2. 性能监控

   • 页面加载性能指标
   • Web Vitals 指标
   • 性能数据上报

3. 数据上报

   • 批量上报机制
   • 重试机制
   • 离线存储

4. 存储管理

   • 数据存储
   • 清理机制

贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。在提交 PR 之前，请确保：

1. 所有测试用例通过
2. 测试覆盖率保持 100%
3. 代码符合项目规范
4. 更新相关文档

提交规范

本项目使用 Commitizen 来规范化提交信息。提交信息格式如下：

<type>(<scope>): <subject>

提交类型

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构代码
• perf: 性能优化
• test: 测试相关
• chore: 构建过程或辅助工具的变动
• revert: 回滚提交

自动提交脚本

项目提供了自动提交脚本，位于 scripts/auto-commit.sh。使用方法：

# 执行脚本
./scripts/auto-commit.sh

# 脚本会自动执行以下操作：
# 1. 添加所有变更文件
# 2. 使用 git-cz 引导输入规范的提交信息
# 3. 推送到远程仓库