npm package: @feiyangdefeng/sdk
Description: 前端全埋点SDK，支持自动埋点、错误监控、性能监控、会话回放等功能
Latest version: 1.1.0

# 前端全埋点SDK

一套完整的前端全埋点SDK，支持自动埋点、错误监控、性能监控、会话回放等功能，具备高性能、高可靠、可扩展和强兼容性。

## 特性

- ✅ **自动埋点**: 页面浏览、点击事件、元素曝光自动采集
- ✅ **错误监控**: JavaScript错误、资源加载错误、Promise错误监控
- ✅ **性能监控**: 页面加载性能、资源加载性能、长任务监控
- ✅ **会话回放**: DOM快照、用户交互记录
- ✅ **用户行为分析**: PV/UV统计、停留时长、访问路径
- ✅ **批量上报**: 数据批量上报，减少网络请求
- ✅ **离线存储**: 网络异常时数据离线存储，网络恢复后自动上报
- ✅ **失败重试**: 指数退避重试策略
- ✅ **数据采样**: 支持配置采样率，减少数据量
- ✅ **插件系统**: 基于事件总线的插件机制，支持网络请求拦截插件
- ✅ **网络请求拦截**: 自动拦截 fetch 和 XMLHttpRequest，记录请求和响应信息（包括响应体）
- ✅ **多环境支持**: 支持浏览器和Node.js环境

## 安装

```bash
pnpm add @feiyangdefeng/sdk
```

## 文档

- [📖 详细使用说明](docs/USAGE.md) - 完整的使用文档，包含所有API、配置选项、使用场景和最佳实践
- [🧪 测试文档](tests/README.md) - 测试覆盖和测试说明

## 快速开始

### 基础使用

```typescript
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'
});
// 设置后，离线存储的数据会自动尝试上报
```

### 自定义埋点

```typescript
// 追踪自定义事件
tracker.track('button-click', {
  buttonName: 'submit',
  page: 'home'
});
```

### 设置用户信息

```typescript
tracker.setUser({
  userId: '123',
  userName: 'John',
  userEmail: 'john@example.com'
});
```

### 手动上报错误

```typescript
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?)

追踪自定义事件。

```typescript
tracker.track('custom-event', {
  key: 'value'
});
```

### setUser(user)

设置用户信息。

```typescript
tracker.setUser({
  userId: '123',
  userName: 'John'
});
```

### getUser()

获取用户信息。

```typescript
const user = tracker.getUser();
```

### trackError(error, errorInfo?)

手动上报错误。

```typescript
tracker.trackError(new Error('Something went wrong'), {
  context: 'payment'
});
```

### trackPerformance()

手动上报性能数据。

```typescript
tracker.trackPerformance();
```

### trackPageView()

手动触发页面浏览追踪。

```typescript
tracker.trackPageView();
```

### use(plugin)

使用插件。

```typescript
const plugin = {
  name: 'my-plugin',
  install(tracker) {
    // 插件逻辑
  }
};

tracker.use(plugin);
```

**网络请求拦截插件**:

```typescript
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)

更新配置。

```typescript
tracker.updateConfig({
  sampleRate: 0.5
});
```

### getConfig()

获取配置。

```typescript
const config = tracker.getConfig();
```

### getBehaviorMetrics()

获取行为分析数据。

```typescript
const metrics = tracker.getBehaviorMetrics();
// { pv: 10, uv: 5, sessions: 3, avgDuration: 5000, paths: [...] }
```

### getSessionReplayData()

获取会话回放数据。

```typescript
const data = tracker.getSessionReplayData();
// { snapshots: [...], interactions: [...] }
```

### destroy()

销毁Tracker实例。

```typescript
tracker.destroy();
```

## 曝光采集

为需要追踪曝光的元素添加 `data-track-exposure` 属性：

```html
<div data-track-exposure>
  需要追踪曝光的内容
</div>
```

## 钩子函数

### beforeSend

上报前钩子，可以修改或取消事件上报。

```typescript
const tracker = new Tracker({
  // ...其他配置
  beforeSend(event) {
    // 修改事件
    event.properties.customField = 'value';
    return event;
    
    // 或者取消上报
    // return false;
  }
});
```

### afterSend

上报后钩子。

```typescript
const tracker = new Tracker({
  // ...其他配置
  afterSend(event, success) {
    if (success) {
      console.log('Event sent successfully');
    }
  }
});
```

## 插件开发

```typescript
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）：

```typescript
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`）。

## 开发

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# 格式化
pnpm format
```

## 技术栈

- **构建工具**: Vite
- **包管理器**: pnpm
- **Node版本**: 18+（使用原生 fetch API）
- **语言**: TypeScript
- **测试**: Vitest

## 更多文档

- [详细使用说明](docs/USAGE.md) - 完整的API文档、配置选项、使用场景和最佳实践
- [测试文档](tests/README.md) - 测试覆盖说明

## 许可证

MIT