hhorg-sensors

@hhorg/analytics

一个为惠灏 H5 项目设计的前端监控和业务分析库。此包提供了强大的监控和业务事件跟踪功能，以确保项目的顺畅运行和洞察性分析。

---

Installation

您可以使用 npm、yarn 或 pnpm 安装此包：

# 使用 npm
npm install @hhorg/analytics

# 使用 yarn
yarn add @hhorg/analytics

# 使用 pnpm
pnpm add @hhorg/analytics

---

Configuration

此包支持通过 unplugin-auto-import 实现 API 自动导入。按照以下步骤在您的 Vue3 项目中配置该库：

1. 安装 unplugin-auto-import

npm install unplugin-auto-import --save-dev

2. 在 vite.config.ts 文件中配置解析器

import autoImport from 'unplugin-auto-import/vite'
import { analyticsResolver } from '@hhorg/analytics/resolver'

export default {
  plugins: [
    autoImport({
      dts: true,
      resolvers: [analyticsResolver()]
    })
  ]
}

3. 创建配置文件并接入 Vue 的 install 钩子

// analytics.config.ts
import { moniter, sensors } from '@hhorg/analytics/vue'

export default {
  install(app, router) {
    moniter.init(app, {
      dsn: '项目错误或性能监控上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
      environment: '根据服务环境配置production或者development',
      release: '配置项目名称',
      router
    })

    // 配置用户信息用于错误报告, 此处应该获取用户真实信息然后进行登录
    moniter.login({
      username: 'errorReport',
      email: '[e-mail]'
    })

    sensors.init(app, {
      dsn: '项目业务数据上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
      environment: '根据服务环境配置production或者development',
      release: '配置项目名称'
    })

    // 配置用户信息用于业务埋点, 此处应该获取用户真实信息然后进行登录
    sensors.login({
      username: 'sensorsReport',
      email: '[e-mail]'
    })

    sensors.autoTrack()
  }
}

4. 在项目入口初始化配置

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import analytics from './analytics.config'

const app = createApp(App)
app.use(router)
// 路由加载完成后初始化
app.use(analytics, router)

5. 在业务代码中直接调用埋点 API

无需显式导入 @hhorg/analytics，可以直接调用以下 API 进行业务埋点：

// 示例：login.vue 页面
sensors.track('事件名称', {
  // 此处为需要上报的数据，请注意字段长度不超过 200 字符
})

完成以上配置后，您可以在项目中直接使用该包的 API, 而无需手动导入。

6. 解决ESLint规则no-undef的报错

修改ESLint的配置文件: .eslintrc.cjs或者eslint.config.js

module.exports = {
  // 添加两个全局变量
  globals: {
    sensors: true,
    moniter: true
  }
  // ...省略其他配置
}

---

API Usage

@hhorg/analytics 包导出了以下对象，下面列出每个对象所包含的主要属性、方法和事件：

Module

Name	Type	Description
moniter	Object	主要用于项目错误监控/性能监控的模块。
sensors	Object	主要用于业务埋点上报的模块。
directive	Object	一个全局 Vue 指令，可以在元素上快速进行简单数据的业务埋点上报（开发中...）。

Methods

模块: moniter

Module	API	Description
moniter	init	Parameters: app: Vue Instance options: { dsn: ''; router: VueRouter; ...Other Sentry.init Config } options还可以传入更多的Sentry配置项, 请参考Sentry文档
moniter	login	Parameters: id: string: 用户的唯一标识符 username: string: 用户名。通常用作比内部 ID 更好的标签 email: string: 用户名的替代或补充。Sentry 可以识别电子邮件地址，并可以显示 Gravatar 等内容并解锁消息传递功能。 ip_address: string: 这个内容由Sentry自动附加 其他数据: string: 用户信息可以扩展其他字段
moniter	track	Parameters: message: string | Error: 用作事件的名称 tags: Object: 用来传递错误数据的上报 extra: Object: 这个字段不是必传的, 在sentry后台无法通过这个字段来检索, 仅仅用来做个大数据的备份
moniter	trackError	Parameters: 传参方式跟moniter.track一致, 唯一的区别是底层将事件级别设置为了'fatal', 而track的级别为'info'
moniter	sentryApi	Parameters: 将sentry的Api暴露出来, 用于更底层的能力, 一般不建议使用

模块: sensors

Module	API	Description
sensors	init	Parameters: app: Vue Instance options: { dsn: ''; allowEventList?: string[]; ...Other Sentry.init Config } allowEventList不是一个必传参数, 业务开发中尽量与产品将事件名称固定到一些范围, 保持在数据面板中的整洁, 便于筛选。options还可以传入更多的Sentry配置项, 请参考Sentry.BrowserClient的配置
sensors	login	Parameters: id: string: 用户的唯一标识符 username: string: 用户名。通常用作比内部 ID 更好的标签 email: string: 用户名的替代或补充。Sentry 可以识别电子邮件地址，并可以显示 Gravatar 等内容并解锁消息传递功能。 ip_address: string: 这个内容由Sentry自动附加 其他数据: string: 用户信息可以扩展其他字段
sensors	track	Parameters: message: string | Error: 用作事件的名称 tags: Object: 用来传递错误数据的上报 extra: Object: 这个字段不是必传的, 在sentry后台无法通过这个字段来检索, 仅仅用来做个大数据的备份
sensors	autoTrack	Parameters: 开启业务埋点中的自动上报功能, 自动上报page_view和page_duration事件
sensors	sentryApi	Parameters: 将sentry的Api暴露出来, 用于更底层的能力, 一般不建议使用

Additional Features

更多 API 和配置选项将在未来的更新中记录。

---

Naming Reference

常用埋点事件的事件名称和事件属性值, 可以参考埋点事件参考规范

---

License

本项目根据 MIT 许可证获得许可。有关详细信息，请参阅 LICENSE 文件。

---

Contributions

欢迎贡献！请随时提交问题、建议或拉取请求以改进库。

---