@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: '[email protected]'
    })

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

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

    // 开启自动埋点, 自动上报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 方法进行埋点。

原生微信小程序接入

1. 创建配置文件 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
        // ...其他用户信息
      })
    }
  })
}

2. 在入口文件中引入配置：

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

App({
  // ...
})

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

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

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

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

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

2. 在 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')]
    })
  ]
}

3. 创建配置文件 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
    // ...其他用户信息
  })
}

4. 在入口文件中引入配置：

// 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
  }
}

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

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

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

四、API Usage

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

Module

Default Event Attributes

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

支持的平台列表:

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

Methods

模块: moniter

模块: sensors

Directive

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

参数说明

Additional Features

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

五、Naming Reference

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

六、License

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

七、Contributions

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