@uxcode-monitor/core

v1.1.26

Published

4 months ago

前端用户体验监控核心库，用于收集和上报用户行为、错误和性能数据

0High
0Medium
0Low

guyuqing33

前端监控用户体验错误收集性能监控用户行为分析

@uxcode-monitor/core

前端用户体验监控核心库，提供事件上报、曝光监测、性能监控等功能，完美支持 Vue 2/3 以及原生 JavaScript 环境。

功能特性

多框架兼容：同时支持 Vue 2 和 Vue 3，提供统一的使用体验
多种引入方式：支持 npm/yarn/pnpm 安装，也支持 CDN 直接引入
事件上报：支持 PV、曝光、点击、自定义事件的上报
曝光监控：自动检测带特定属性的元素曝光
动态元素支持：使用 MutationObserver 监听 DOM 变化，支持动态加载的元素
钩子函数：提供多个生命周期钩子，方便自定义处理逻辑
轻量级：体积小，性能影响低

安装

NPM

npm install @uxcode-monitor/core --save

Yarn

yarn add @uxcode-monitor/core

PNPM

pnpm add @uxcode-monitor/core

使用方法

1. Vue 3 项目中使用

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import uxMonitor from '@uxcode-monitor/core'

const app = createApp(App)

// 安装监控插件
app.use(uxMonitor, {
  autoCollectAppear: true, // 是否自动收集曝光事件
  registerBeforeCreateParams: (baseData: any) => {
    // 自定义添加参数
    console.log("registerBeforeCreateParams")
    return { ...baseData, customParam: "111" }
  },
  registerBeforeUpload: (data: any) => {
    // 处理上报数据，添加自定义参数
    console.log("registerBeforeUpload", data)
    return { ...data, customParam: "value" }
  },
  afterUpload: (url: any, data: any) => {
    // 上报后的回调
    console.log("数据已上报", url, data)
  }
})

app.mount('#app')

2. Vue 2 项目中使用

// main.js
import Vue from 'vue'
import App from './App.vue'
import uxMonitor from '@uxcode-monitor/core'

// 安装插件
Vue.use(uxMonitor, {
  autoCollectAppear: true, // 是否自动收集曝光事件
  registerBeforeCreateParams: (baseData) => {
    // 自定义添加参数
    console.log("registerBeforeCreateParams")
    return { ...baseData, gyq: "111" }
  },
  registerBeforeUpload: (data) => {
    // 自定义添加参数
    console.log("registerBeforeUpload", data)
    return { ...data, customParam: "value" }
  },
  afterUpload: (url, data) => {
    // 上报后的回调
    console.log("数据已上报", url, data)
  }
})
Vue.prototype.$uxMonitor = uxMonitor

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

3. 在 Vue 3 组件中使用（组合式 API）

<script setup lang="ts">
import { inject } from 'vue'
import type { UxMonitorInstance } from '@uxcode-monitor/core'

// 注入 uxMonitor 实例
const uxMonitor = inject<UxMonitorInstance>('uxMonitor')!

// 发送点击事件
function handleClick() {
  uxMonitor.sendClick({
    buttonId: 'my-button',
    action: 'submit'
  })
}

// 发送曝光事件
function handleExpose() {
  uxMonitor.sendExp({
    appearId: 'my-element',
    appearInfo: { position: 'top' }
  })
}
</script>

<template>
  <button @click="handleClick">点击按钮</button>
  <!-- 自动曝光监控 -->
  <div appear appear-id="promotion-banner" appear-info="{'position': 'top'}">
    曝光元素
  </div>
</template>

4. 在 Vue 2 组件中使用（选项式 API）

<script>
export default {
  name: 'MyComponent',
  methods: {
    handleClick() {
      // 通过 this.$uxMonitor 访问实例
      this.$uxMonitor.sendClick({
        buttonId: 'my-button',
        action: 'submit'
      })
    }
  }
}
</script>

<template>
  <button @click="handleClick">点击按钮</button>
</template>

5. 原生 JavaScript 使用（ESM 导入）

// 引入监控库
import { sendPV, sendClick, sendExp, sendCustom } from '@uxcode-monitor/core'

// 发送 PV 事件
sendPV({ pageTitle: '首页' })

// 发送点击事件
sendClick({ buttonId: 'login', action: 'click' })

// 发送曝光事件
sendExp({ appearId: 'banner', appearInfo: { position: 'top' } })

// 发送自定义事件
sendCustom({ eventName: 'custom', eventData: { key: 'value' } })

6. CDN 直接引入

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>CDN 引入示例</title>
  <!-- 引入 @uxcode-monitor/core -->
  <script src="https://cdn.jsdelivr.net/npm/@uxcode-monitor/core/dist/index.global.js"></script>
</head>
<body>
  <div id="app">
    <button id="my-button">点击我</button>
    <div appear appear-id="expose-div">曝光元素</div>
  </div>
  
  <script>
    // 初始化配置
    uxMonitor.init({
      autoCollectAppear: true
    })
    
    // 发送 PV 事件
    uxMonitor.sendPV({ pageTitle: 'CDN 示例页面' })
    
    // 绑定点击事件
    document.getElementById('my-button').addEventListener('click', function() {
      uxMonitor.sendClick({
        buttonId: 'my-button',
        action: 'click'
      })
    })
    
    // 手动发送曝光事件
    uxMonitor.sendExp({
      appearId: 'manual-expose',
      appearInfo: { type: 'manual' }
    })
  </script>
</body>
</html>

曝光监控

自动曝光

为元素添加 appear 属性和 appear-id 属性，当元素进入视口时会自动上报曝光事件：

<div appear appear-id="promotion-banner" appear-info="{'position': 'top'}">
  曝光元素
</div>

appear：标记元素需要监控曝光
appear-id：元素唯一标识，必填
appear-info：可选，JSON 字符串格式的附加信息

手动曝光

也可以通过 API 手动上报曝光事件：

// Vue 组件内
this.$uxMonitor.sendExp({
  appearId: 'custom-element',
  appearInfo: { 
    position: 'center',
    type: 'banner'
  },
  targetTag: 'div'
})

// CDN 模式下
uxMonitor.sendExp({
  appearId: 'custom-element',
  appearInfo: { 
    position: 'center',
    type: 'banner'
  }
})

API 说明

1. 初始化配置方法

init(config?: MonitorConfig)

初始化监控配置

参数：

config: 可选，监控配置对象

返回值：

使用场景：

CDN 模式下手动初始化
原生 JavaScript 项目中初始化

2. 事件上报方法

sendPV(data?: Record<string, any>)

上报 PV 事件

参数：

data: 可选，PV 事件数据
- pageTitle: 页面标题
- pageUrl: 页面 URL
- 其他自定义字段

返回值：

sendExp(data: Record<string, any>)

上报曝光事件

参数：

data: 曝光事件数据
- appearId: 元素唯一标识，必填
- appearInfo: 附加信息对象
- targetTag: 目标元素标签名

返回值：

sendClick(data: Record<string, any>)

上报点击事件

参数：

data: 点击事件数据
- buttonId: 按钮唯一标识，必填
- action: 动作类型
- targetName: 目标名称

返回值：

sendCustom(data: Record<string, any>)

上报自定义事件

参数：

data: 自定义事件数据
- eventName: 事件名称，必填
- eventData: 事件数据对象
- 其他自定义字段

返回值：

collectAppear()

手动收集所有带有 appear 属性的元素进行曝光监控

参数：

返回值：

3. 钩子函数注册

registerBeforeCreateParams(callback: (data: Record<string, any>) => Record<string, any>)

注册参数创建前的钩子函数，用于自定义上报参数

参数：

callback: 回调函数，接收原始数据，返回处理后的数据

返回值：

registerBeforeUpload(callback: (data: Record<string, any>) => Record<string, any> | false)

注册上传前的钩子函数，可以修改数据或阻止上传

参数：

callback: 回调函数，接收即将上传的数据，返回处理后的数据或 false（阻止上传）

返回值：

registerAfterUpload(callback: (url: string, data: Record<string, any>) => void)

注册上传后的钩子函数

参数：

callback: 回调函数，接收上传 URL 和数据

返回值：

registerErrorHandler(callback: (error: Error | string) => void)

注册错误处理钩子函数

参数：

callback: 回调函数，接收错误对象或错误信息

返回值：

配置项详解

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | autoCollectAppear | boolean | false | 是否自动收集曝光事件 | | beforeCreateParams | function | undefined | 参数创建前的钩子函数，接收原始数据，返回处理后的数据 | | beforeUpload | function | undefined | 上传前的钩子函数，接收即将上传的数据，返回处理后的数据或 false（阻止上传） | | afterUpload | function | undefined | 上传后的钩子函数，接收上传 URL 和数据 | | onError | function | console.error | 错误处理函数，接收错误对象或错误信息 | | collectAppearInterval | number | 1000 | 自动收集曝光元素的时间间隔（毫秒） | | uploadUrl | string | '' | 数据上报地址，默认为空，需要自定义实现上传逻辑 |

事件类型

| 事件类型 | 说明 | 对应方法 | |----------|------|----------| | PV | 页面访问事件 | sendPV | | EXP | 曝光事件 | sendExp | | CLICK | 点击事件 | sendClick | | CUSTOM | 自定义事件 | sendCustom |

浏览器兼容性

Vue 3 模式

Chrome 58+
Firefox 54+
Safari 12+
Edge 79+

Vue 2 模式

Chrome 49+
Firefox 45+
Safari 10+
Edge 16+

CDN 模式

兼容所有现代浏览器和 IE 11（需要 polyfill）

注意事项

通用注意事项

确保在浏览器环境中使用，不支持 Node.js 环境
自动曝光监控仅在 autoCollectAppear 设置为 true 时生效
对于动态加载的内容，库会自动通过 MutationObserver 检测新元素

Vue 2 特别注意事项

Vue 2 中，插件会自动挂载到 Vue.prototype.$uxMonitor
使用 Vue.use(uxMonitor) 安装插件时，配置项中的函数要使用普通函数，避免使用箭头函数
在使用 TypeScript 的 Vue 2 项目中，可能需要扩展 Vue 接口以获得类型支持

CDN 引入特别注意事项

CDN 模式下，所有方法直接挂载在全局变量 uxMonitor 上
建议先调用 uxMonitor.init() 方法进行初始化配置
如需使用高级特性，确保引入最新版本

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@uxcode-monitor/core

功能特性

安装

NPM

Yarn

PNPM

使用方法

1. Vue 3 项目中使用

2. Vue 2 项目中使用

3. 在 Vue 3 组件中使用（组合式 API）

4. 在 Vue 2 组件中使用（选项式 API）

5. 原生 JavaScript 使用（ESM 导入）

6. CDN 直接引入

曝光监控

自动曝光

手动曝光

API 说明

1. 初始化配置方法

init(config?: MonitorConfig)

2. 事件上报方法

sendPV(data?: Record<string, any>)

sendExp(data: Record<string, any>)

sendClick(data: Record<string, any>)

sendCustom(data: Record<string, any>)

collectAppear()

3. 钩子函数注册

registerBeforeCreateParams(callback: (data: Record<string, any>) => Record<string, any>)

registerBeforeUpload(callback: (data: Record<string, any>) => Record<string, any> | false)

registerAfterUpload(callback: (url: string, data: Record<string, any>) => void)

registerErrorHandler(callback: (error: Error | string) => void)

配置项详解

事件类型

浏览器兼容性

Vue 3 模式

Vue 2 模式

CDN 模式

注意事项

通用注意事项

Vue 2 特别注意事项

CDN 引入特别注意事项