H2O Web Monitor SDK

Web 前端监控 SDK，用于收集性能数据、错误日志和用户行为数据。提供灵活的配置选项和多种上报方式。

✨ 特性

• 多种上报方式：支持 HTTP (POST)、Image (GET)、Beacon API 上报。
• 设备指纹：集成 FingerprintJS 获取唯一设备 ID，并在初始化时自动缓存。
• 异步初始化：支持异步初始化，提供 ready() 接口确保上报时机。
• 配置灵活：支持自定义上报地址、版本号、渠道、平台等信息。
• TypeScript：完全使用 TypeScript 编写，提供完整的类型定义。
• 构建优化：基于 Rollup 构建，支持 ESM 和 UMD 格式。
• Vue 支持：提供 Vue 2/3 插件和 Composition API 支持。

📦 安装

npm install @yule-h2o/web_monitor_sdk
# 或者
pnpm add @yule-h2o/web_monitor_sdk

🚀 快速开始

方式 1：使用单例实例（推荐，任意框架 / 原生）

import { H2OWebMonitor } from '@yule-h2o/web_monitor_sdk';

// 初始化 SDK（异步）
await H2OWebMonitor.init({
  baseURL: 'https://your-report-endpoint.com/report',
  reporterType: 'http', // 'http' | 'beacon' | 'image'
  version: '1.0.0',
  channels: 'official',
  platform: 'web',
  debug: false
});

// 上报数据
H2OWebMonitor.report({
  level: 'ERROR',
  error_info: 'Uncaught TypeError: Cannot read property of undefined',
  // 自定义字段
  uid: 'user_123',
  email: '[email protected]'
});

方式 1b：使用 ready() 确保初始化完成

import { H2OWebMonitor } from '@yule-h2o/web_monitor_sdk';

// 先初始化
H2OWebMonitor.init({
  baseURL: 'https://your-report-endpoint.com/report',
  debug: true
});

// 在需要上报的地方等待初始化完成
await H2OWebMonitor.ready();
H2OWebMonitor.report({
  level: 'INFO',
  error_info: 'User action'
});

方式 1c：创建独立实例

import { H2OWebMonitorSDK } from '@yule-h2o/web_monitor_sdk';

// 创建新实例（非单例）
const sdk = new H2OWebMonitorSDK();
await sdk.init({
  baseURL: 'https://your-report-endpoint.com/report',
  reporterType: 'http'
});

sdk.report({
  level: 'ERROR',
  error_info: 'Error message'
});

方式 2：Vue 3 插件

import { createApp } from 'vue';
import App from './App.vue';
import { H2OWebMonitorVue } from '@yule-h2o/web_monitor_sdk';

const app = createApp(App);

app.use(H2OWebMonitorVue, {
  baseURL: 'https://your-report-endpoint.com/report',
  reporterType: 'http',
  platform: 'vue3',
  debug: true
});

app.mount('#app');

在组件中使用（script setup）：

import { useMonitor } from '@yule-h2o/web_monitor_sdk';

const monitor = useMonitor();

// 等待初始化完成后上报
monitor?.ready().then(() => {
  monitor?.report({
    level: 'INFO',
    error_info: 'User clicked button'
  });
});

方式 3：Vue 2 接入

使用插件方式安装（会挂到 Vue.prototype.$monitor）：

import Vue from 'vue';
import App from './App.vue';
import { H2OWebMonitorVue } from '@yule-h2o/web_monitor_sdk';

Vue.use(H2OWebMonitorVue, {
  baseURL: 'https://your-report-endpoint.com/report',
  reporterType: 'http',
  platform: 'vue2'
});

new Vue({
  render: h => h(App)
}).$mount('#app');

在组件中使用：

export default {
  methods: {
    async reportSomething() {
      await this.$monitor.ready();
      this.$monitor.report({
        level: 'INFO',
        error_info: 'Vue2 event'
      });
    }
  }
};

⚙️ 配置选项 (SDKOptions)

初始化 SDK 时可传入以下配置项：

| 参数 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | baseURL | string | '' | 上报接口的基础 URL | | reporterType | 'http' \| 'beacon' \| 'image' | 'http' | 上报方式 | | version | string | '1.0.0' | 应用版本号 | | channels | string | '' | 应用发布渠道 | | platform | string | 'web' | 运行平台标识 | | debug | boolean | false | 是否开启调试模式 |

📄 API

H2OWebMonitorSDK

SDK 类，可通过 new H2OWebMonitorSDK() 创建独立实例，或使用导出的单例 H2OWebMonitor。

init(options: SDKOptions, callback?: () => void): Promise<void>

初始化 SDK。在初始化过程中，SDK 会自动异步获取并缓存设备 ID。

await H2OWebMonitor.init({
  baseURL: 'https://your-report-endpoint.com/report',
  reporterType: 'http'
});

ready(): Promise<void>

等待 SDK 初始化完成。如果 SDK 尚未调用 init()，会返回 rejected Promise。

// 确保初始化完成后再上报
await H2OWebMonitor.ready();
H2OWebMonitor.report({ ... });

report(data: ReportParams): void

上报监控数据。该方法会附带基础信息（如 version, channels, deviceId, platform, error_time）一同上报。

注意：

• 如果 SDK 尚未初始化完成，上报数据会被暂存，初始化完成后自动发送
• level 字段会自动转换为大写
• 兼容老字段 error_type，会自动映射为 level（不推荐，建议迁移）

ReportParams 接口定义：

interface ReportParams {
  uid?: string;
  email?: string;
  country?: string;
  lang?: string;
  version?: string;
  channels?: string;
  platform?: string;
  deviceId?: string;
  error_time?: string;  // 自动填充，可选
  level: string;   // 必填，如 'ERROR', 'WARN', 'INFO', 'DEBUG'
  error_info: string;   // 必填
  /**
   * @deprecated 请使用 level 字段
   */
  error_type?: string;
}

getOptions(): ResolvedSDKOptions

获取 SDK 当前的配置（包含默认值）。

useMonitor()

Vue Composition API，用于在组件中获取 SDK 实例。

import { useMonitor } from '@yule-h2o/web_monitor_sdk';

const monitor = useMonitor();
// monitor 等同于 H2OWebMonitor 单例实例

License

MIT