💚 Vue.js 接入文档

支持 Vue 2 / Vue 3，自动追踪 Vue Router 路由变化，Composition API 友好

Vue.js 接入

澄泓统计提供 Vue 专用插件，支持 Vue 2 和 Vue 3，自动集成 Vue Router，路由切换时自动上报页面浏览事件。

💡 前置条件：请先在后台添加站点获取 Tracking ID（格式如 tid_xxxxxxxxxx）。

Vue 3 接入

1. 安装插件

在 main.js / main.ts 中引入并注册插件：

js 
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import LightAnalytics from 'light-analytics/vue'

const app = createApp(App)

app.use(router)
app.use(LightAnalytics, {
  tid: 'tid_xxxxxxxxxx',        // 你的 Tracking ID
  router: router,                // 传入 router 实例，自动追踪路由变化
  // serverUrl: 'https://your-domain',  // 私有化部署时填你的服务地址
  // debug: false,                         // 开启调试模式，控制台打印上报信息
  // consent: 'auto'                        // 'auto' 自动采集，'explicit' 需用户同意后采集
})

app.mount('#app')
✅ 自动功能：传入 router 后，插件会自动监听路由变化，每次路由切换自动上报 pageview，无需手动调用。

2. Composition API 使用

在组件中通过 useAnalytics() 获取实例，手动上报自定义事件：

vue 
<script setup>
import { useAnalytics } from 'light-analytics/vue'

const analytics = useAnalytics()

// 上报自定义事件
function handlePurchase() {
  analytics.trackEvent('purchase', {
    amount: 99,
    product: 'Pro版',
    currency: 'CNY'
  })
}

// 手动上报页面浏览（一般不需要，自动路由已处理）
// analytics.trackPageview()

// 用户ID关联（登录后调用）
function onLogin(userId) {
  analytics.identify(userId, {
    plan: 'pro',
    email: 'u***@example.com'
  })
}
</script>

<template>
  <button @click="handlePurchase">购买Pro版</button>
</template>

3. Options API 使用

在 Options API 中通过 this.$analytics 访问：

js 
export default {
  methods: {
    onSubmit() {
      this.$analytics.trackEvent('form_submit', {
        form: 'contact'
      })
    }
  }
}

Vue 2 接入

1. 安装插件

js 
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import LightAnalytics from 'light-analytics/vue2'

Vue.use(LightAnalytics, {
  tid: 'tid_xxxxxxxxxx',
  router: router
})

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

2. 组件中使用

js 
export default {
  mounted() {
    this.$analytics.trackEvent('page_viewed', {
      page: 'home'
    })
  }
}

Nuxt 3 接入

在 Nuxt 3 项目中，创建插件文件 plugins/analytics.client.ts（.client 确保只在客户端执行）：

ts 
// plugins/analytics.client.ts
import { defineNuxtPlugin, useRouter } from '#app'
import LightAnalytics from 'light-analytics/vue'

export default defineNuxtPlugin((nuxtApp) => {
  const router = useRouter()

  nuxtApp.vueApp.use(LightAnalytics, {
    tid: 'tid_xxxxxxxxxx',
    router: router
  })
})

Nuxt 2 接入

在 nuxt.config.js 中添加插件：

js 
// plugins/analytics.js
import Vue from 'vue'
import LightAnalytics from 'light-analytics/vue2'

export default ({ app }) => {
  Vue.use(LightAnalytics, {
    tid: 'tid_xxxxxxxxxx',
    router: app.router
  })
}

// nuxt.config.js
export default {
  plugins: [
    { src: '~/plugins/analytics.js', mode: 'client' }
  ]
}

API 参考

插件配置选项

  • tid (必填)：Tracking ID
  • router：Vue Router 实例，传入后自动追踪路由变化
  • serverUrl：私有化部署的服务端地址
  • debug：是否开启调试模式，默认 false
  • consent：'auto' 自动采集 | 'explicit' 需用户同意
  • autoTrack：是否自动追踪点击、表单提交，默认 true

实例方法

js 
// 手动上报页面浏览
analytics.trackPageview(path?, title?)

// 上报自定义事件
analytics.trackEvent(name, properties?)

// 关联用户ID（登录后调用）
analytics.identify(userId, traits?)

// 用户同意采集（GDPR 严格模式下使用）
analytics.grantConsent()

// 用户拒绝采集
analytics.denyConsent()

// 开启/关闭调试
analytics.setDebug(true/false)
⚠️ 注意：插件默认使用 history 模式监听路由。如果你使用 hash 模式，请确保 router 配置中 history: createWebHashHistory()，插件会自动适配。