更新记录

0.1.1（2026-06-12） 下载此版本

更新文档信息

0.1.0（2026-06-12） 下载此版本

【0.1.0】

平台兼容性

uni-app(5.0)

其他

tracker 埋点采集插件

tracker 是一款面向 uni-app 的轻量级跨端埋点采集插件，支持 H5 和 uni-app 小程序端的页面曝光、页面切换、点击、输入、事件计时与批量上报。

特性

• 轻量无依赖，适合直接放入 uni_modules
• 支持 H5 与 uni-app 小程序端
• 自动采集页面进入 / 离开事件
• 支持自定义事件、公共属性、用户标识
• 支持事件计时，自动生成 _duration
• 支持批量上报、采样率、队列上限、定时 flush
• H5 支持 v-track 指令，便于快速接入交互埋点

安装

将 uni_modules/hello-i-tracker 目录放入项目根目录的 uni_modules 中即可使用，不需要额外执行 npm install。

如果你是复制到新项目，推荐保持以下结构：

uni_modules/
  hello-i-tracker/
    src/
    examples/
    package.json
    README.md

快速开始

Vue2

import Vue from 'vue'
import App from './App'
import { createTracker } from '@/uni_modules/hello-i-tracker/src'

const tracker = createTracker({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com/collect',
  debug: process.env.NODE_ENV === 'development',
  sampleRate: 1,
  batchSize: 10,
  flushInterval: 5000,
  enableAutoTrack: true,
  Vue
})

Vue.prototype.$tracker = tracker
Vue.config.productionTip = false

App.mpType = 'app'

new Vue({
  ...App
}).$mount()

Vue3

import { createSSRApp } from 'vue'
import App from './App'
import { createTracker } from '@/uni_modules/hello-i-tracker/src'

export function createApp() {
  const app = createSSRApp(App)

  const tracker = createTracker({
    appId: 'your-app-id',
    endpoint: 'https://your-domain.com/collect',
    debug: import.meta.env.DEV,
    Vue: app
  })

  app.config.globalProperties.$tracker = tracker
  return { app }
}

API

创建实例

const tracker = createTracker({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com/collect',
  Vue,
  userId: '',
  debug: false,
  sampleRate: 1,
  batchSize: 10,
  flushInterval: 5000,
  maxQueueSize: 500,
  enableAutoTrack: true,
  version: '0.1.0'
})

实例方法

指令埋点

H5

H5 支持点击、输入、变更和曝光指令：

<button v-track:click="{ event: 'buy_click', data: { sku: '123' } }">
  购买
</button>

<input v-track:input="{ event: 'search_input', data: { debounce: 300 } }" />

<div v-track:expose="{ event: 'banner_expose', data: { id: 1 } }">
  <img src="banner.jpg" />
</div>

data.debounce 仅对 input / change 生效。

小程序

当前实现中，小程序端主要可靠支持 v-track:expose。 交互类指令由于平台限制，建议直接调用 track()。

事件计时

tracker.startTimer('page_load')

// ...

tracker.endTimer('page_loaded', 'page_load', {
  page: 'home'
})

上报事件会自动附带 _duration。

公共属性

tracker.setUserId('user_12345')

tracker.setGlobalProps({
  channel: 'mini-program',
  appVersion: '1.2.0'
})

tracker.setEventProps({
  vipLevel: 3
})

setEventProps() 会兼容合并到全局属性，便于后续事件复用。

后端接收示例

app.post('/collect', (req, res) => {
  const { appId, sessionId, events, timestamp } = req.body

  events.forEach(event => {
    console.log({
      ...event,
      appId,
      sessionId,
      receivedAt: Date.now()
    })
  })

  res.json({ ok: true, timestamp })
})

请求体结构大致如下：

{
  "appId": "your-app-id",
  "sessionId": "uuid",
  "events": [
    {
      "event": "button_click",
      "data": { "id": "submit" },
      "timestamp": 1718160000000,
      "sessionId": "uuid",
      "userId": "user_123",
      "page": "pages/order/index",
      "device": {
        "platform": "h5",
        "screenWidth": 375,
        "screenHeight": 812
      }
    }
  ],
  "timestamp": 1718160000000
}

平台说明

注意事项

• appId 和 endpoint 为必填项
• sampleRate 取值范围为 0 ~ 1
• H5 的交互类指令可直接使用，小程序端建议优先手动调用 track()
• 页面自动采集依赖运行时注入，Vue2 请传入 Vue，Vue3 请传入 Vue: app
• 页面隐藏或应用切后台时，插件会尝试自动 flush，失败数据会进入本地缓存并在下次恢复时继续上报

目录结构

src/
  adapters/
  core/
  modules/
  utils/
examples/

License

MIT