前端监控 SDK，支持页面访问、性能监控、错误追踪、用户行为和网络请求监控

Monitor SDK 使用指南

一个功能完整的前端监控 SDK，支持页面访问、性能监控、错误追踪、用户行为和网络请求监控。

安装

NPM 安装

bash 复制代码

npm install @wangyahao/monitor-sdk

CDN 引入

html 复制代码

<!-- UMD 格式 -->
<script src="https://unpkg.com/@wangyahao/monitor-sdk/dist/monitor.umd.min.js"></script>

<!-- 或者使用未压缩版本用于调试 -->
<script src="https://unpkg.com/@wangyahao/monitor-sdk/dist/monitor.umd.js"></script>

这两个地址是假的，

使用方法

1. ES Module 方式

javascript 复制代码

import { MonitorSDK } from '@wangyahao/monitor-sdk';

// 创建 SDK 实例
const monitor = new MonitorSDK({
  reportUrl: 'https://your-server.com/api/monitor',
  appId: 'your-app-id',
  useBeacon: true,
  sampleRate: 1,
  autoClick: true,
  autoNetwork: true,
  debug: false
});

2. UMD 方式（浏览器直接引入）

html 复制代码

<script src="dist/monitor.umd.min.js"></script>
<script>
  // SDK 会自动初始化，也可以通过全局变量访问
  const monitor = window.monitorSDK;
  
  // 或者使用命令队列方式
  window._monitor = window._monitor || [];
  window._monitor.push(['config', {
    reportUrl: 'https://your-server.com/api/monitor',
    appId: 'your-app-id'
  }]);
</script>

3. 命令队列方式（推荐）

html 复制代码

<script>
  // 在 SDK 加载前就可以使用
  window._monitor = window._monitor || [];
  
  // 配置 SDK
  _monitor.push(['config', {
    reportUrl: 'https://your-server.com/api/monitor',
    appId: 'your-app-id',
    sampleRate: 0.1, // 10% 采样率
    debug: true
  }]);
  
  // 手动追踪页面访问
  _monitor.push(['trackPageView']);
  
  // 设置用户 ID
  _monitor.push(['setUserId', 'user123']);
  
  // 追踪自定义事件
  _monitor.push(['trackEvent', 'button_click', { button: 'submit' }]);
  
  // 设置自定义属性
  _monitor.push(['setCustom', 'version', '1.0.0']);
  
  // 手动上报
  _monitor.push(['flush']);
</script>

<!-- 异步加载 SDK -->
<script async src="dist/monitor.umd.min.js"></script>

TypeScript 支持

typescript 复制代码

import { MonitorSDK, type MonitorConfig } from '@wangyahao/monitor-sdk';

// 完整的类型支持
const config: MonitorConfig = {
  reportUrl: 'https://your-server.com/api/monitor',
  appId: 'your-app-id',
  sampleRate: 0.1
};

const monitor = new MonitorSDK(config);

配置选项

typescript 复制代码

interface MonitorConfig {
  reportUrl: string;          // 上报接口地址（必填）
  appId: string;              // 应用 ID（必填）
  useBeacon?: boolean;        // 优先使用 sendBeacon（默认 true）
  sampleRate?: number;        // 采样率 0-1（默认 1）
  batchMax?: number;          // 单次批量上报最大条数（默认 20）
  flushIntervalMs?: number;   // 批量上报间隔毫秒（默认 10000）
  autoClick?: boolean;        // 自动点击事件追踪（默认 true）
  autoNetwork?: boolean;      // 自动网络请求监控（默认 true）
  beforeSend?: (payload) => payload | null; // 数据预处理函数
  debug?: boolean;            // 调试模式（默认 false）
}

API 方法

直接调用方式

javascript 复制代码

// 设置用户 ID
monitor.identify('user123');

// 设置自定义属性
monitor.setCustom('version', '1.0.0');

// 追踪自定义事件
monitor.trackCustom('purchase', { 
  product: 'premium', 
  amount: 99.99 
});

命令队列方式

javascript 复制代码

// 所有方法都可以通过命令队列调用
_monitor.push(['setUserId', 'user123']);
_monitor.push(['setCustom', 'version', '1.0.0']);
_monitor.push(['trackEvent', 'purchase', { product: 'premium' }]);
_monitor.push(['trackPageView']);
_monitor.push(['flush']);

自动监控功能

SDK 会自动监控以下内容：

页面访问：页面加载时自动发送 pageview 事件
性能指标：FP、FCP、LCP、TTFB、DOM 加载时间等
错误监控：JavaScript 错误、Promise 拒绝、资源加载错误
用户行为：点击事件（可配置关闭）
网络请求：Fetch 和 XMLHttpRequest 监控（可配置关闭）
页面停留时间：页面卸载时自动上报

数据格式

上报的数据格式：

json 复制代码

{
  "events": [
    {
      "appId": "your-app-id",
      "type": "pageview",
      "timestamp": 1640995200000,
      "sessionId": "session-uuid",
      "userId": "user123",
      "pageUrl": "https://example.com/page",
      "referrer": "https://google.com",
      "userAgent": "Mozilla/5.0...",
      "data": {
        "pageTitle": "页面标题",
        "screenWidth": 1920,
        "screenHeight": 1080
      }
    }
  ]
}

最佳实践

采样率设置：生产环境建议设置合适的采样率（如 0.1）以减少服务器压力
数据脱敏 ：使用 beforeSend 函数对敏感数据进行脱敏处理
错误处理：监控上报接口的可用性，避免影响主业务
性能优化：使用 CDN 加速 SDK 加载，采用异步加载方式

构建命令

bash 复制代码

# 完整构建
npm run build

# 开发环境构建
npm run build:dev

# 生产环境构建
npm run build:prod

# 监听模式构建
npm run dev

# 清理构建产物
npm run clean

输出文件

dist/monitor.esm.js - ES Module 格式
dist/monitor.esm.min.js - ES Module 压缩版
dist/monitor.umd.js - UMD 格式
dist/monitor.umd.min.js - UMD 压缩版
dist/monitor.d.ts - TypeScript 类型声明

故障排除

模块找不到问题

如果遇到 "找不到模块或其相应的类型声明" 错误：

确认包名正确：

javascript 复制代码

// ✅ 正确
import { MonitorSDK } from '@wangyahao/monitor-sdk';

// ❌ 错误
import { MonitorSDK } from 'monitor-sdk';

检查安装：
bash 复制代码
```
npm list @wangyahao/monitor-sdk
```
TypeScript 配置 ：确保 tsconfig.json 中的 moduleResolution 设置正确：
json 复制代码
```
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}
```

重新安装：

bash 复制代码

npm uninstall @wangyahao/monitor-sdk
npm install @wangyahao/monitor-sdk

构建工具配置

Webpack：无需额外配置，支持开箱即用

Vite：无需额外配置，支持开箱即用

Rollup ：确保安装了 @rollup/plugin-node-resolve

浏览器兼容性

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

License

MIT