@feiyangdefeng/sdk

v1.1.0

Published

2 months ago

前端全埋点SDK，支持自动埋点、错误监控、性能监控、会话回放等功能

0High
0Medium
0Low

feiyangdefeng

tracker analytics sdk 埋点监控

前端全埋点SDK

一套完整的前端全埋点SDK，支持自动埋点、错误监控、性能监控、会话回放等功能，具备高性能、高可靠、可扩展和强兼容性。

特性

✅ 自动埋点: 页面浏览、点击事件、元素曝光自动采集
✅ 错误监控: JavaScript错误、资源加载错误、Promise错误监控
✅ 性能监控: 页面加载性能、资源加载性能、长任务监控
✅ 会话回放: DOM快照、用户交互记录
✅ 用户行为分析: PV/UV统计、停留时长、访问路径
✅ 批量上报: 数据批量上报，减少网络请求
✅ 离线存储: 网络异常时数据离线存储，网络恢复后自动上报
✅ 失败重试: 指数退避重试策略
✅ 数据采样: 支持配置采样率，减少数据量
✅ 插件系统: 基于事件总线的插件机制，支持网络请求拦截插件
✅ 网络请求拦截: 自动拦截 fetch 和 XMLHttpRequest，记录请求和响应信息（包括响应体）
✅ 多环境支持: 支持浏览器和Node.js环境

安装

pnpm add @feiyangdefeng/sdk

文档

📖 详细使用说明 - 完整的使用文档，包含所有API、配置选项、使用场景和最佳实践
🧪 测试文档 - 测试覆盖和测试说明

快速开始

基础使用

import Tracker from '@feiyangdefeng/sdk';

// 方式1: 设置服务器地址（推荐）
const tracker = new Tracker({
  appId: 'your-app-id',
  serverUrl: 'https://api.example.com/track',
  enableAutoTrack: true,
  enableErrorTrack: true,
  enablePerformanceTrack: true
});

// 方式2: 不设置服务器地址（仅本地收集，数据保存到离线存储）
const offlineTracker = new Tracker({
  appId: 'your-app-id',
  enableOfflineStorage: true  // 建议启用
  // serverUrl 不设置时，数据会保存到离线存储
});

// 后续可以设置serverUrl
offlineTracker.updateConfig({
  serverUrl: 'https://api.example.com/track'
});
// 设置后，离线存储的数据会自动尝试上报

自定义埋点

// 追踪自定义事件
tracker.track('button-click', {
  buttonName: 'submit',
  page: 'home'
});

设置用户信息

tracker.setUser({
  userId: '123',
  userName: 'John',
  userEmail: '[email protected]'
});

手动上报错误

try {
  // 业务代码
} catch (error) {
  tracker.trackError(error, {
    context: 'payment',
    orderId: '12345'
  });
}

配置选项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | - | 应用ID（必填） | | serverUrl | string | - | 上报服务器地址（可选，不设置时数据仅保存到离线存储） | | enableAutoTrack | boolean | true | 是否启用自动埋点 | | enableErrorTrack | boolean | true | 是否启用错误监控 | | enablePerformanceTrack | boolean | false | 是否启用性能监控 | | enableSessionReplay | boolean | false | 是否启用会话回放 | | batchSize | number | 10 | 批量上报大小 | | batchWait | number | 5000 | 批量上报等待时间（毫秒） | | sampleRate | number | 1.0 | 采样率（0-1） | | enableOfflineStorage | boolean | true | 是否启用离线存储 | | maxRetries | number | 3 | 最大重试次数 | | userId | string | '' | 用户ID | | deviceId | string | '' | 设备ID（自动生成） | | customProperties | object | {} | 自定义属性 | | beforeSend | function | - | 上报前钩子 | | afterSend | function | - | 上报后钩子 | | onError | function | - | 错误处理函数 |

API

track(eventName, properties?)

追踪自定义事件。

tracker.track('custom-event', {
  key: 'value'
});

setUser(user)

设置用户信息。

tracker.setUser({
  userId: '123',
  userName: 'John'
});

getUser()

获取用户信息。

const user = tracker.getUser();

trackError(error, errorInfo?)

手动上报错误。

tracker.trackError(new Error('Something went wrong'), {
  context: 'payment'
});

trackPerformance()

手动上报性能数据。

tracker.trackPerformance();

trackPageView()

手动触发页面浏览追踪。

tracker.trackPageView();

use(plugin)

使用插件。

const plugin = {
  name: 'my-plugin',
  install(tracker) {
    // 插件逻辑
  }
};

tracker.use(plugin);

网络请求拦截插件:

import Tracker, { networkInterceptorPlugin, createNetworkInterceptorPlugin } from '@feiyangdefeng/sdk';

const tracker = new Tracker({
  appId: 'my-app',
  serverUrl: 'https://api.example.com/track'
});

// 使用默认配置
tracker.use(networkInterceptorPlugin);

// 或使用自定义配置
const customNetworkPlugin = createNetworkInterceptorPlugin({
  urlFilter: /^https?:\/\/api\./, // 只记录 API 请求
  recordResponseBody: true, // 记录响应体
  sensitiveFields: ['password', 'token'] // 过滤敏感字段
});
tracker.use(customNetworkPlugin);

updateConfig(config)

更新配置。

tracker.updateConfig({
  sampleRate: 0.5
});

getConfig()

获取配置。

const config = tracker.getConfig();

getBehaviorMetrics()

获取行为分析数据。

const metrics = tracker.getBehaviorMetrics();
// { pv: 10, uv: 5, sessions: 3, avgDuration: 5000, paths: [...] }

getSessionReplayData()

获取会话回放数据。

const data = tracker.getSessionReplayData();
// { snapshots: [...], interactions: [...] }

destroy()

销毁Tracker实例。

tracker.destroy();

曝光采集

为需要追踪曝光的元素添加 data-track-exposure 属性：

<div data-track-exposure>
  需要追踪曝光的内容
</div>

钩子函数

beforeSend

上报前钩子，可以修改或取消事件上报。

const tracker = new Tracker({
  // ...其他配置
  beforeSend(event) {
    // 修改事件
    event.properties.customField = 'value';
    return event;
    
    // 或者取消上报
    // return false;
  }
});

afterSend

上报后钩子。

const tracker = new Tracker({
  // ...其他配置
  afterSend(event, success) {
    if (success) {
      console.log('Event sent successfully');
    }
  }
});

插件开发

import type { TrackerPlugin } from '@feiyangdefeng/sdk';

const myPlugin: TrackerPlugin = {
  name: 'my-plugin',
  install(tracker) {
    // 监听事件
    // 修改配置
    // 扩展功能
  },
  uninstall(tracker) {
    // 清理工作
  }
};

tracker.use(myPlugin);

性能优化

SDK采用异步加载，不阻塞页面渲染
使用事件委托，避免内存泄漏
数据批量上报，减少网络请求
支持采样，减少数据量
使用Web Worker处理数据（可选）

浏览器兼容性

Chrome (最新版)
Firefox (最新版)
Safari (最新版)
Edge (最新版)

Node.js支持

SDK支持在Node.js环境中使用（需要 Node.js 18+，因为使用了原生 fetch API）：

import Tracker from '@feiyangdefeng/sdk';

const tracker = new Tracker({
  appId: 'your-app-id',
  serverUrl: 'https://api.example.com/track'
});

tracker.track('server-event', {
  server: 'node'
});

注意: SDK 使用 Node.js 18+ 原生支持的 fetch API，无需安装额外的依赖（如 node-fetch）。

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# 格式化
pnpm format

技术栈

构建工具: Vite
包管理器: pnpm
Node版本: 18+（使用原生 fetch API）
语言: TypeScript
测试: Vitest

许可证

MIT