@pzds/frontend-tracking

🚀 PZDS 前端埋点收集上报 SDK，支持点击事件、页面访问、元素曝光等多种埋点类型

📦 安装

# 使用 npm
npm install @pzds/frontend-tracking

# 使用 yarn
yarn add @pzds/frontend-tracking

# 使用 pnpm
pnpm add @pzds/frontend-tracking

🚀 快速开始

基础用法

import frontSightSDK from '@pzds/frontend-tracking'

// 配置数据上报接口
const trackRecord = (data, options) => {
  return fetch('/api/tracking', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  })
}

// 初始化埋点系统
const autoTracking = frontSightSDK.useWebAutoTracking(router, trackRecord)
autoTracking.init()

// 应用销毁时清理
autoTracking.destroy()

Vue.js 集成

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import frontSightSDK from '@pzds/frontend-tracking'

const app = createApp(App)

const trackRecord = (data) => {
  return fetch('/api/tracking', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  })
}

const autoTracking = frontSightSDK.useWebAutoTracking(router, trackRecord)

app.mount('#app')
autoTracking.init()

// 清理
window.addEventListener('beforeunload', () => {
  autoTracking.destroy()
})

Nuxt.js 集成

// plugins/tracking.client.js
import frontSightSDK from '@pzds/frontend-tracking'

export default defineNuxtPlugin(nuxtApp => {
  const router = useRouter()
  
  const trackRecord = (data) => {
    return $fetch('/api/tracking', {
      method: 'POST',
      body: data
    })
  }
  
  const autoTracking = frontSightSDK.useWebAutoTracking(router, trackRecord)

  nuxtApp.hook('app:mounted', () => {
    autoTracking.init()
  })

  nuxtApp.hook('app:beforeDestroy', () => {
    autoTracking.destroy()
  })
})

✨ 特性

• 🎯 多种埋点类型 - 支持点击、页面访问、元素曝光等
• 🔄 自动采集 - 无需手动配置即可采集基础用户行为
• 📊 批量上报 - 智能批量处理，提升性能
• 🚀 轻量级 - 压缩后仅 9.5KB
• 🛡️ TypeScript - 完整的类型定义支持
• 🌐 框架无关 - 支持 Vue、React、原生 JS 等
• ⚡ 防抖优化 - 避免重复上报，提升用户体验

📖 API 文档

自动埋点

SDK 会自动收集以下事件：

| 事件类型 | 描述 | 触发时机 | |---------|------|---------| | click | 点击事件 | 用户点击页面元素时 | | pageView | 页面访问 | 路由切换时 | | pageLoad | 页面加载 | 页面加载完成时 | | pageRefresh | 页面离开 | 页面刷新或关闭时 | | exposure | 元素曝光 | 元素进入可视区域时 |

手动埋点

点击埋点

<!-- 基础点击埋点 -->
<button data-track-click='{"action":"submit","category":"form"}'>
  提交
</button>

<!-- 动态数据埋点 -->
<button 
  v-for="item in list"
  :data-track-click="JSON.stringify({ eventName: item.name, id: item.id })"
>
  {{ item.name }}
</button>

曝光埋点

<!-- 立即曝光 -->
<div :data-track-exposure='JSON.stringify({ eventName: "banner_view" })'>
  广告横幅
</div>

<!-- 批量曝光（每6个上报一次） -->
<div :data-track-exposure="JSON.stringify({ 
  _type: 'batch', 
  module_id: 'product_list', 
  param: { productId: item.id } 
})">
  商品卡片
</div>

<!-- 时长曝光 -->
<div :data-track-exposure="JSON.stringify({ 
  _type: 'duration', 
  eventName: 'video_view' 
})">
  视频内容
</div>

📋 事件数据结构

点击事件 (click)

interface ClickEvent {
  eventType: 'click'
  elementType: string
  pageUrl: string
  timestamp: number
  targetInfo: {
    tagName: string
    className: string
    id: string
    textContent: string
  }
  trackParams?: Record<string, any>
  device_info: DeviceInfo
}

页面访问事件 (pageView)

interface PageViewEvent {
  eventType: 'pageView'
  timestamp: number
  fromPath: string
  toPath: string
  device_info: DeviceInfo
}

元素曝光事件 (exposure)

interface ExposureEvent {
  eventType: 'exposure'
  timestamp: number
  elementType: string
  trackId: string
  duration: number
  pageUrl: string
  device_info: DeviceInfo
  [key: string]: any // 自定义参数
}

设备信息 (DeviceInfo)

interface DeviceInfo {
  userAgent: string
  screenWidth: number
  screenHeight: number
  language: string
}

⚙️ 配置选项

初始化配置

const autoTracking = frontSightSDK.useWebAutoTracking(router, trackRecord, {
  // 批量上报数量（默认：6）
  batchSize: 6,
  
  // 防抖延迟时间（默认：500ms）
  debounceTime: 500,
  
  // 点击去重时间（默认：300ms）
  clickDedupeTime: 300,
  
  // 是否启用自动采集（默认：true）
  autoCapture: true
})

🌍 浏览器兼容性

| 浏览器 | 版本要求 | |--------|----------| | Chrome | >= 60 | | Firefox | >= 60 | | Safari | >= 12 | | Edge | >= 79 |

📝 更新日志

v1.0.1

• 📚 更新文档格式和结构
• 🐛 修复示例代码中的小问题

v1.0.0

• 🎉 首次发布到 npm
• ✨ 支持点击、页面访问、元素曝光等多种埋点类型
• ✨ 支持自动埋点和手动埋点
• ✨ 完整的 TypeScript 类型支持

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请联系 PZDS 前端团队。