UniApp 日志上报 SDK

一个专为 UniApp 应用设计的日志采集与上报 SDK，支持自动采集网络请求、原生事件、错误日志、音频播放等多种数据，并提供灵活的上报配置。

功能特性

• 自动采集 - 自动拦截网络请求、原生事件、错误信息、音频播放等
• 手动上报 - 支持自定义业务日志的手动上报
• 灵活配置 - 支持按职责分组配置上报通道、脱敏规则、采集过滤和上报策略
• Vue 插件 - 支持 Vue2/Vue3 插件方式安装
• 类型支持 - 完整的 TypeScript 类型定义

安装

npm install getui-oa-log-sdk-uniapp
# 或
yarn add getui-oa-log-sdk-uniapp

快速开始

1. Vue 插件方式（推荐）

import { createApp } from 'vue';
import App from './App.vue';
import LogSDK from 'getui-oa-log-sdk-uniapp';

const app = createApp(App);

// 基础使用 - 使用默认配置
app.use(LogSDK);

// 自定义配置
app.use(LogSDK, {
  // 启用/禁用上报
  enabled: true,

  // 自定义上报函数
  reporter: (data) => {
    console.log('上报数据:', data);
    // 自定义上报逻辑，如发送到自建服务器
  },

  transport: {
    // 默认原生上报事件名
    eventName: 'monitorReport',
  },

  sanitize: {
    // 排除的请求头（保护敏感信息）
    excludeHeaders: ['Authorization', 'cookie', 'X-Token'],
  },

  collect: {
    // 忽略的原生事件，避免采集噪音或上报回环
    ignoreNativeEventNames: ['commonEvent'],
  },

  policy: {
    websocket: true,
    audio: ['create', 'play', 'pause', 'error'],
  },
});

app.mount('#app');

2. 手动上报日志

import { reportLog } from 'getui-oa-log-sdk-uniapp';

// 简单上报
reportLog({ message: '用户点击了购买按钮' });

// 带标签上报（支持多个标签）
reportLog({ message: '用户点击了购买按钮', productId: '123' }, 'userAction', 'purchase', 'button');

配置选项

| 配置项 | 类型 | 默认值 | 说明 | | ------------------ | ------------------- | ----------------- | ------------------------------- | | enabled | boolean | true | 上报开关，false时停止所有上报 | | reporter | ReporterFunction | defaultReporter | 自定义上报函数 | | transport | ITransportConfig | 见下方默认配置 | 默认上报通道配置 | | sanitize | ISanitizeConfig | 见下方默认配置 | 数据脱敏配置 | | collect | ICollectConfig | 见下方默认配置 | 采集阶段过滤配置 | | policy | ITypeReportPolicy | 见下方默认策略 | 按日志类型和事件控制上报方式 | | cacheLogMaxCount | number | 50 | 日志缓存最大数量 |

API 文档

核心函数

reportLog(data, ...tags)

手动上报日志。

参数：

• data - 要上报的数据对象
• tags - 可选的标签数组，用于分类筛选

示例：

reportLog({ message: '操作成功' }, 'success', 'api');

配置接口

IReportConfig

interface IReportConfig {
  /** 上报开关，默认开启 */
  enabled?: boolean;

  /** 自定义上报函数 */
  reporter?: ReporterFunction;

  /** 缓存日志最大数量 */
  cacheLogMaxCount?: number;

  transport?: {
    eventName?: string;
  };

  sanitize?: {
    excludeHeaders?: string[];
  };

  collect?: {
    ignoreNativeEventNames?: string[];
  };

  /** 按日志类型控制上报方式 */
  policy?: {
    network?: boolean;
    event?: boolean;
    error?: boolean;
    custom?: boolean;
    websocket?: boolean | string[];
    audio?: boolean | string[];
  };
}

默认配置：

• transport.eventName: 'monitorReport'
• sanitize.excludeHeaders: ['Authorization', 'cookie']
• collect.ignoreNativeEventNames: []

policy 的规则如下：

• boolean
  • true：开启该类型上报并使用默认策略
  • false：关闭该类型上报
• string[]
  • 仅适用于 websocket 和 audio
  • 只上报数组中的事件

兼容说明：

• reportEventName 兼容映射到 transport.eventName
• excludeHeaders 兼容映射到 sanitize.excludeHeaders
• whiteEventNames 兼容映射到 collect.ignoreNativeEventNames
• reportPolicy 兼容映射到 policy
• 新旧字段同时传时，新字段优先

默认策略：

• network: true：保持当前错误时上报
• event: true
• error: true
• custom: true
• websocket: true：默认上报 connect、open、close、error，不报 message
• audio: true：默认上报 create、play、pause、stop、ended、error

IReportData

上报数据的结构：

interface IReportData {
  appName: string; // 应用名称
  appVersion: string; // 应用版本
  appId: string; // 应用ID
  logType: string; // 日志类型（http/event/error/audio/custom）
  time: string; // 上报时间
  baseUrl: any; // 基础URL
  userInfo: any; // 用户信息
  page: string; // 当前页面路由
  data: any; // 具体数据内容
}

ReporterFunction

自定义上报函数类型：

type ReporterFunction = (data: IReportData) => void;

高级用法

自定义上报函数

import LogSDK, { IReportData } from 'getui-oa-log-sdk-uniapp';

app.use(LogSDK, {
  reporter: (data: IReportData) => {
    // 自定义上报逻辑
    uni.request({
      url: 'https://your-server.com/log',
      method: 'POST',
      data: data,
      success: () => {
        console.log('上报成功');
      },
      fail: (err) => {
        console.error('上报失败:', err);
      },
    });
  },
});

排除敏感请求头

app.use(LogSDK, {
  sanitize: {
    // 完全自定义排除的请求头
    excludeHeaders: ['Authorization', 'cookie', 'X-Token', 'X-Secret'],
  },

  // 不排除任何请求头（谨慎使用）
  // sanitize: { excludeHeaders: [] }
});

忽略原生事件

app.use(LogSDK, {
  collect: {
    // 这些原生事件不会被 SDK 劫持采集
    ignoreNativeEventNames: ['heartbeat', 'pageScroll', 'touchMove'],
  },
});

动态控制上报开关

import { REPORT_CONFIG } from 'getui-oa-log-sdk-uniapp';

// 临时关闭上报
REPORT_CONFIG.enabled = false;

// 重新开启上报
REPORT_CONFIG.enabled = true;

控制 WebSocket 和 Audio 上报

app.use(LogSDK, {
  policy: {
    // 默认策略：开启 websocket 上报，但不报 message
    websocket: true,

    // 完全关闭 audio 上报
    audio: false,
  },
});

app.use(LogSDK, {
  policy: {
    // 只上报指定 websocket 事件
    websocket: ['open', 'close', 'error'],

    // 只上报指定 audio 事件
    audio: ['create', 'play', 'pause', 'error'],
  },
});

兼容旧配置写法

以下旧字段写法仍然兼容一段时间，但新接入建议使用分组后的新结构：

app.use(LogSDK, {
  reportEventName: 'monitorReport',
  excludeHeaders: ['Authorization', 'cookie'],
  whiteEventNames: ['heartbeat'],
  reportPolicy: {
    websocket: ['open', 'error'],
  },
});

自动采集的数据类型

SDK 会自动采集以下类型的日志：

1. HTTP 请求日志

自动拦截 uni.request、uni.uploadFile、uni.downloadFile、uni.connectSocket 等网络请求。

上报时机： 当响应的 errno !== 0 时自动上报

数据内容：

• 请求方法、URL、参数
• 响应数据（排除敏感请求头后）
• 请求耗时

2. 原生事件日志

自动拦截 uni.sendNativeEvent、uni.onNativeEventReceive 等原生通信。

3. 错误日志

自动捕获 uni.onError 错误，以及 JS 运行时的错误。

4. 音频日志

自动拦截 uni.createInnerAudioContext 创建的音频实例的所有操作和事件。

5. 自定义日志

通过 reportLog 函数手动上报的日志。

数据结构示例

HTTP 错误日志

{
  "appName": "MyApp",
  "appVersion": "1.0.0",
  "appId": "__UNI__XXXXXXX",
  "logType": "http",
  "time": "2024-01-15 10:30:25.123",
  "baseUrl": "https://api.example.com",
  "userInfo": { "userId": "12345" },
  "page": "pages/index/index",
  "data": {
    "type": "request",
    "request": {
      "url": "/api/user/info",
      "method": "GET"
    },
    "response": {
      "errno": 500,
      "errMsg": "服务器错误"
    },
    "startTime": 1705319425123,
    "endTime": 1705319425234
  }
}

自定义日志

{
  "appName": "MyApp",
  "appVersion": "1.0.0",
  "appId": "__UNI__XXXXXXX",
  "logType": "custom",
  "time": "2024-01-15 10:30:25.123",
  "baseUrl": "https://api.example.com",
  "userInfo": { "userId": "12345" },
  "page": "pages/index/index",
  "data": {
    "tags": "userAction,purchase",
    "message": "用户点击了购买按钮",
    "productId": "123"
  }
}

注意事项

1. 上报事件排除 - SDK 会自动排除 transport.eventName 对应的事件，避免死循环
2. H5 环境 - 在 H5 环境下，console.log 拦截会被禁用，以免 log 展示位置错误
3. 敏感信息 - 默认会排除 Authorization 和 cookie 请求头，保护用户敏感信息
4. 日志缓存 - 各类日志都有缓存数量限制，超过限制会自动移除最早的日志

浏览器兼容性

• App - 完全支持（iOS/Android）
• 小程序 - 完全支持（微信小程序、支付宝小程序等）
• H5 - 支持，但 console.log 拦截被禁用

License

MIT