@hhorg/analytics

@hhorg/analytics

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

一、Installation

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

# 使用 npm
npm install @hhorg/analytics

# 使用 yarn
yarn add @hhorg/analytics

# 使用 pnpm
pnpm add @hhorg/analytics

二、在HTML5中接入

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

1. 安装 unplugin-auto-import

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

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

通过配置解析器，您可以在项目中自动导入 moniter、sensors 和 directive 等多个模块对象，而无需在每个文件中手动导入它们。这不仅简化了代码，还减少了手动导入的错误风险。

在 Module 中注明的模块, 均不需要显示导入。具体的模块功能和使用方法可以参考 Module 章节。

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

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

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

// analytics.config.ts
import { moniter, sensors, directive } 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: '配置项目名称',
      router
    })

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

    // 开启自动埋点, 自动上报page_view和page_duration事件
    sensors.autoTrack()

    // 注册全局埋点指令
    directive.register(app)
  }
}

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. 埋点方式一、使用自定义指令 v-track

在模板中使用 v-track 指令, 使用语法如下:

<div v-trak:[原生事件名称]:[埋点事件名称]="埋点数据对象 | 埋点数据函数">
  This is Home Page
</div>

以下是在项目中使用的具体示例:

<template>
  <!-- 示例：点击事件 -->
  <button v-track:click:click_material="clickParams">点击我</button>
  <!-- 示例：鼠标悬停事件 -->
  <div v-track:mouseover:mouse_material="clickParams">悬停查看</div>
  <!-- 示例：曝光事件 -->
  <button v-track:default:view_material="viewParams">按钮曝光</button>
  <!-- 或者省略原生事件default关键字 -->
  <button v-track:view_material="viewParams">按钮曝光</button>
  <!-- 示例：动态参数传递 -->
  <button v-track:click:dynamic_click_track="clickToTrack">
    点击传递动态参数
  </button>
</template>

<script setup lang="ts">
  import { ref } from 'vue'

  const clickParams = ref({
    user_id: 'xiaohui',
    page_id: 'http://xxx',
    page_title: '粉红丝带详情页',
    button_name: '分享',
    card_id: 'xxx'
  })

  const viewParams = ref({
    user_id: 'xiaohui',
    page_id: 'http://xxx',
    page_title: '粉红丝带详情页',
    share_link: 'http://xxx',
    share_btn_info: '去分享'
  })

  // 仅需要返回一个埋点上报的对象即可
  const clickToTrack = (event) => {
    return {
      event_target: event.target.innerText,
      user_id: 'xiaohui',
      share_link: 'http://xxx',
      share_btn_info: '动态参数传递'
    }
  }
</script>

6. 埋点方式二、在业务代码中直接调用埋点 API进行埋点

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

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

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

[!WARNING] 在开发中, 一般需要把事件名称规范起来。例如点击事件，请使用click_material, 曝光事件使用view_material, 埋点的数据中, 所有键名使用下划线命名

// 点击事件
sensors.track('click_material', {
  user_id: 'xiaohui',
  page_id: 'http://xxx',
  page_title: '粉红丝带详情页',
  button_name: '分享',
  card_id: 'xxx'
})

// 曝光事件
sensors.track('view_material', {
  user_id: 'xiaohui',
  page_id: 'http://xxx',
  page_title: '粉红丝带详情页',
  share_link: 'http://xxx',
  share_btn_info: '去分享'
})

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

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

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

三、在小程序中接入

注意:

小程序中不支持指令方式的埋点, 只能使用 sensors.track 方法进行埋点。

原生微信小程序接入

• 创建配置文件 examples/miniapp/analytics.config.js，内容如下：

const { moniter, sensors } = require('@hhorg/analytics')

// 用于项目监控初始化
module.exports = function useAnalytics(release) {
  moniter.init({
    dsn: '项目错误或性能监控上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
    environment: '根据服务环境配置production或者development',
    release
  })

  // 用于业务埋点初始化
  sensors.init({
    dsn: '项目错误或性能监控上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
    environment: '根据服务环境配置production或者development',
    release
  })

  // 这块登录不是强制性的, 如果不登录, 会使用匿名用户, 在后台显示IP地址
  // 如果能获取用户的openid, 可以使用下面的方式来登录
  wx.login({
    success: (res) => {
      // 发送 res.code 到后台换取 openId, sessionKey, unionId
      moniter.login({
        id: userInfo.openid
        // ...其他用户信息
      })
      sensors.login({
        id: userInfo.openid
        // ...其他用户信息
      })
    }
  })
}

• 在入口文件中引入配置：

// examples/miniapp/app.js
const useAnalytics = require('./analytics.config.js')
useAnalytics('xiaohui-app-mini')

App({
  // ...
})

• 在业务代码中直接调用埋点 API进行埋点

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

第三方跨平台框架接入(uniapp/taro)

如果使用了vite之类的打包工具, 可以配置auto-import插件, 自动导入moniter、sensors 等多个模块对象, 而无需在每个文件中手动导入它们。

• 自动导入参考在HTML5中接入#1. 安装 unplugin-auto-import

• 在 vite.config.ts 文件中配置解析器, 参考在HTML5中接入#2. 在 vite.config.ts 文件中配置解析器

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

export default {
  plugins: [
    autoImport({
      dts: true,
      // 特别注意, 这里需要传入'miniapp'参数
      resolvers: [analyticsResolver('miniapp')]
    })
  ]
}

• 创建配置文件 examples/miniapp/analytics.config.js，内容如下：

import { sensors, moniter } from '@hhorg/analytics/miniapp'

// 用于项目监控初始化
export function useAnalytics(release) {
  moniter.init({
    dsn: '项目错误或性能监控上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
    environment: '根据服务环境配置production或者development',
    release
  })

  // 用于业务埋点初始化
  sensors.init({
    dsn: '项目错误或性能监控上报的远端服务 URL, 在 Sentry 的后台创建项目后配置',
    environment: '根据服务环境配置production或者development',
    release
  })

  // 这块登录不是强制性的, 如果不登录, 会使用匿名用户, 在后台显示IP地址
  // 如果能获取用户的openid, 可以调用moniter.login和sensors.login来进行登录
  // 此处应该获取用户信息后, 使用用户id来登录, 小程序中可以使用openid
  const userInfo = 'getUserInfo()...'
  moniter.login({
    id: userInfo.openid
    // ...其他用户信息
  })
  sensors.login({
    id: userInfo.openid
    // ...其他用户信息
  })
}

• 在入口文件中引入配置：

// main.ts
import { createSSRApp } from 'vue'
import { createPinia } from 'pinia'
import './styles/iconfont.css'
import './styles/common.scss'
import App from './App.vue'
import { useAnalytics } from './analytics.config.js'

export function createApp() {
  const app = createSSRApp(App)
  const pinia = createPinia()
  app.use(pinia)
  useAnalytics('xiaohui-app-mini')

  return {
    app
  }
}

• 在业务代码中直接调用埋点 API进行埋点

业务代码中无需导入sensors对象, 直接调用sensors.track方法进行埋点

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

四、API Usage

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

Module

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

Default Event Attributes

在埋点事件中，系统会自动添加以下默认属性：

属性名称	类型	说明
_path	string	当前页面的路径。
_current_url	string	当前页面的完整 URL。
_date	string	事件发生的日期和时间。
_timestamp	number	事件发生的时间戳（秒）。
_user_agent	string	用户代理字符串。
_platform	string	用户的平台信息。支持的平台列表见下表
_timestamp_unit	'second'	时间戳的单位，默认是秒。
_page_title	string	当前页面的标题。
_duration	number	页面停留时长，单位为秒。
_duration_unit	'second'	时长的单位，默认是秒。
_referrer_path	string	上一个页面的路径。
_referrer_url	string	上一个页面的 URL。

支持的平台列表:

字段	值	平台	备注
_platform	wx_web	微信浏览器
_platform	wx_mini	微信小程序
_platform	app_ios	IOS客户端
_platform	app_android	安卓客户端
_platform	sys_ios	苹果系统浏览器
_platform	sys_android	安卓系统浏览器

Methods

模块: moniter

Module	API	Description
moniter	init	Parameters: app: Vue Instance options: { dsn: string; router: VueRouter; environment: 'production' | 'development'; release: stirng, // ...Other Sentry.init options } 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: string; allowEventList?: string[]; router?: VueRouter; environment: 'production' | 'development'; release: stirng, // ...Other Sentry.BrowserClient init options } 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暴露出来, 用于更底层的能力, 一般不建议使用

Directive

在 Vue 项目中，您可以使用自定义指令 v-track 来实现埋点功能。该指令允许您在指定的原生事件触发时进行埋点上报。

参数说明

参数	类型	说明
原生事件类型	string	可以是任何 addEventListener 支持的事件名称，如 click、mouseover 等。省略或使用 default 表示曝光埋点。
埋点事件名称	string	必须使用下划线命名法（如 click_material、view_material）。
事件参数	Record	一个 JavaScript 对象，包含需要上报的埋点数据。

Additional Features

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

五、Naming Reference

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

六、License

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

七、Contributions

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