# 监听工具SDK

**Repository Path**: huang_zhan_le/monitoring-tool-sdk

## Basic Information

- **Project Name**: 监听工具SDK
- **Description**: 使用rollup+ts实现的前端信息收集工具SDK，包含错误收集、行为收集、console异常收集、promise错误收集、http错误收集，主动上报等，简单易用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 前端异常监控SDK

一个功能完整的前端异常监控SDK，用于拦截和上报异常信息、性能数据和用户行为。

## 功能特性

- 🚨 **错误监控**: 自动捕获JavaScript错误、Promise错误、资源加载错误、HTTP请求错误
- 📊 **性能监控**: 监控页面加载性能、Web Vitals指标
- 👤 **用户行为追踪**: 追踪用户点击、滚动、输入、页面导航等行为
- 📡 **数据上报**: 支持定时上报、页面卸载上报、网络错误重试
- ⚙️ **可配置**: 支持采样率、缓存大小、上报间隔等配置
- 🔧 **TypeScript**: 完整的TypeScript类型支持
- 📦 **模块化**: 支持ES模块、CommonJS、UMD等多种模块格式

## 安装

```bash
npm install error-monitor-sdk
```

## 快速开始

### 基本使用

```javascript
import createErrorMonitorSDK from 'error-monitor-sdk';

// 创建SDK实例
const errorMonitor = createErrorMonitorSDK();

// 初始化SDK
errorMonitor.init({
  reportUrl: 'https://your-api.com/error-report',
  appId: 'your-app-id',
  appVersion: '1.0.0',
  userId: 'user-123',
  enableConsole: true,
  enablePerformance: true,
  enableBehavior: true,
  sampleRate: 1.0,
  maxCacheSize: 100,
  reportInterval: 5000,
  tags: {
    environment: 'production',
    version: '1.0.0'
  }
});
```

### 手动上报错误

```javascript
// 上报Error对象
try {
  // 你的代码
} catch (error) {
  errorMonitor.reportError(error, {
    context: 'user-action',
    userId: 'user-123'
  });
}

// 上报字符串错误
errorMonitor.reportError('Custom error message', {
  severity: 'high',
  component: 'payment-form'
});
```

### 事件监听

```javascript
// 监听错误事件
errorMonitor.on('error', (errorInfo) => {
  console.log('捕获到错误:', errorInfo);
});

// 监听性能事件
errorMonitor.on('performance', (performanceInfo) => {
  console.log('性能数据:', performanceInfo);
});

// 监听用户行为事件
errorMonitor.on('behavior', (behaviorInfo) => {
  console.log('用户行为:', behaviorInfo);
});
```

## 配置选项

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `reportUrl` | string | ✅ | - | 上报服务器地址 |
| `appId` | string | ✅ | - | 应用标识 |
| `appVersion` | string | ❌ | - | 应用版本 |
| `userId` | string | ❌ | - | 用户标识 |
| `enableConsole` | boolean | ❌ | false | 是否启用控制台错误监控 |
| `enablePerformance` | boolean | ❌ | true | 是否启用性能监控 |
| `enableBehavior` | boolean | ❌ | false | 是否启用用户行为追踪 |
| `sampleRate` | number | ❌ | 1.0 | 采样率 (0-1) |
| `maxCacheSize` | number | ❌ | 100 | 最大缓存数量 |
| `reportInterval` | number | ❌ | 5000 | 上报间隔时间(ms) |
| `tags` | object | ❌ | {} | 自定义标签 |

## API 文档

### 主要方法

#### `init(config: SDKConfig)`
初始化SDK，开始监控。

#### `reportError(error: Error | string, extra?: Record<string, any>)`
手动上报错误信息。

#### `reportPerformance(performance: PerformanceInfo)`
手动上报性能信息。

#### `reportBehavior(behavior: BehaviorInfo)`
手动上报用户行为。

#### `on(event: string, listener: Function)`
添加事件监听器。

#### `off(event: string, listener: Function)`
移除事件监听器。

#### `flush()`
强制上报所有缓存数据。

#### `destroy()`
销毁SDK，停止监控。

#### `getStatus()`
获取SDK状态信息。

### 使用
~~~js
// 初始化SDK
window.initSDK = function() {
    sdk = window.ErrorMonitorSDK.default();
    sdk.init({
        reportUrl: 'https://api.example.com/error-report',
        appId: 'demo-app',
        appVersion: '1.0.0',
        userId: 'demo-user',
        enableConsole: true,
        enablePerformance: true,
        enableBehavior: true,
        sampleRate: 1.0,
        maxCacheSize: 100,
        reportInterval: 5000,
        tags: {
            environment: 'demo',
            version: '1.0.0'
        }
    });
    // 事件监听
    sdk.on('error', (errorInfo) => {
        log('捕获到错误', errorInfo);
        console.log('捕获到错误:', errorInfo);
    });
    sdk.on('performance', (performanceInfo) => {
        log('性能数据', performanceInfo);
        console.log('性能数据:', performanceInfo);
    });
    sdk.on('behavior', (behaviorInfo) => {
        log('用户行为', behaviorInfo);
        console.log('用户行为:', behaviorInfo);
    });
    updateStatus();
};
// 销毁SDK
window.destroySDK = function() {
    if (sdk) sdk.destroy();
    sdk = null;
    updateStatus();
    log('SDK已销毁');
};
~~~

### 事件类型

#### error 事件
当捕获到错误时触发。

```typescript
interface ErrorInfo {
  type: 'js' | 'promise' | 'resource' | 'http' | 'custom';
  message: string;
  stack?: string;
  filename?: string;
  lineno?: number;
  colno?: number;
  timestamp: number;
  url: string;
  userAgent: string;
  extra?: Record<string, any>;
}
```

#### performance 事件
当收集到性能数据时触发。

```typescript
interface PerformanceInfo {
  loadTime: number;
  domContentLoadedTime: number;
  fcp?: number;
  lcp?: number;
  fid?: number;
  cls?: number;
  timestamp: number;
}
```

#### behavior 事件
当检测到用户行为时触发。

```typescript
interface BehaviorInfo {
  type: 'click' | 'scroll' | 'input' | 'navigation' | 'custom';
  selector?: string;
  text?: string;
  url: string;
  timestamp: number;
  extra?: Record<string, any>;
}
```

## 上报数据格式

SDK会将监控数据按以下格式上报到服务器：

```typescript
interface ReportData {
  appId: string;
  appVersion?: string;
  userId?: string;
  sessionId: string;
  errors?: ErrorInfo[];
  performance?: PerformanceInfo;
  behaviors?: BehaviorInfo[];
  tags?: Record<string, any>;
  timestamp: number;
}
```

## 构建

```bash
# 安装依赖
npm install

# 构建SDK
npm run build

# 开发模式
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint
```

## 浏览器兼容性

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## 注意事项

1. **隐私保护**: 用户行为追踪功能会收集用户交互数据，请确保符合隐私法规。
2. **网络请求**: SDK会定期发送HTTP请求，请确保上报服务器稳定可靠。
3. **性能影响**: 建议在生产环境中使用适当的采样率以减少性能影响。
4. **错误处理**: SDK内部错误不会影响应用正常运行。

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！ 

### API 说明
sdk.init(config) 初始化 SDK
sdk.reportError(error, extra?) 手动上报错误
sdk.reportPerformance(performance) 手动上报性能
sdk.reportBehavior(behavior) 手动上报行为
sdk.on(event, listener) 监听事件（error/performance/behavior）
sdk.off(event, listener) 移除事件监听
sdk.getStatus() 获取当前状态
sdk.flush() 强制上报缓存
sdk.destroy() 销毁 SDK

### 监听的行为
- 1.点击事件
- 2.滚动事件
- 3.输入事件
- 4.导航事件（代理导航方法）

### 监听错误
- 1.监听js错误（监听error）
- 2.监听Promise错误（监听unhandledrejection）
- 3.监听资源加载错误（监听error）
- 4.监听HTTP请求错误（代理XMLHttpRequest对象和Fetch对象）
- 5.监听控制台错误（代理console.error和console.warn）

### 监听性能
- 1.监听加载中（loading）
- 2.监听DOM加载完成（DOMContentLoaded）
- 3.监听页面完全加载（load）
- 4.监听页面可见性（visibilitychange）