npm package: @pzds/frontend-tracking
Description: PZDS 前端埋点收集上报 SDK，支持点击事件、页面访问、元素曝光等多种埋点类型
Author: pz
Latest version: 1.0.6

# @pzds/frontend-tracking

> 🚀 PZDS 前端埋点收集上报 SDK，支持点击事件、页面访问、元素曝光等多种埋点类型

[![npm version](https://img.shields.io/npm/v/@pzds/frontend-tracking.svg)](https://www.npmjs.com/package/@pzds/frontend-tracking)
[![npm downloads](https://img.shields.io/npm/dm/@pzds/frontend-tracking.svg)](https://www.npmjs.com/package/@pzds/frontend-tracking)
[![license](https://img.shields.io/npm/l/@pzds/frontend-tracking.svg)](https://github.com/pzds/frontend-tracking/blob/main/LICENSE)

## 📦 安装

```bash
# 使用 npm
npm install @pzds/frontend-tracking

# 使用 yarn
yarn add @pzds/frontend-tracking

# 使用 pnpm
pnpm add @pzds/frontend-tracking
```

## 🚀 快速开始

### 基础用法

```javascript
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 集成

```javascript
// 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 集成

```javascript
// 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` | 元素曝光 | 元素进入可视区域时 |

### 手动埋点

#### 点击埋点

```html
<!-- 基础点击埋点 -->
<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>
```

#### 曝光埋点

```html
<!-- 立即曝光 -->
<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)

```typescript
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)

```typescript
interface PageViewEvent {
  eventType: 'pageView'
  timestamp: number
  fromPath: string
  toPath: string
  device_info: DeviceInfo
}
```

### 元素曝光事件 (exposure)

```typescript
interface ExposureEvent {
  eventType: 'exposure'
  timestamp: number
  elementType: string
  trackId: string
  duration: number
  pageUrl: string
  device_info: DeviceInfo
  [key: string]: any // 自定义参数
}
```

### 设备信息 (DeviceInfo)

```typescript
interface DeviceInfo {
  userAgent: string
  screenWidth: number
  screenHeight: number
  language: string
}
```

## ⚙️ 配置选项

### 初始化配置

```javascript
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](LICENSE)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

如有问题，请联系 PZDS 前端团队。