event-tracking-guide.md 5.86 KB

Raw Blame History Permalink



埋点功能使用指南


概述

项目提供了统一的事件埋点功能，通过 useEventTracking Composable 实现各种用户行为的追踪。


核心文件


API 接口: src/api/event.js - 埋点 API 接口定义

Composable: src/composables/useEventTracking.js - 埋点逻辑封装

集成组件: src/components/ListItemActions/index.vue - 已集成埋点功能


快速开始


1. 在列表页面使用（已集成）

ListItemActions 组件已自动集成埋点功能，只需传递 itemId prop：

<template>
  <ListItemActions
    :item-id="item.id"
    @view="handleView"
  />
</template>

<script setup>
import ListItemActions from '@/components/ListItemActions/index.vue'

const item = {
  id: 'file-123',
  name: '保险产品手册'
}

const handleView = () => {
  // 点击查看时，自动发送埋点数据
  console.log('查看文件')
}
</script>


2. 自定义埋点


基础用法

<script setup>
import { useEventTracking, EventType } from '@/composables/useEventTracking'

const { trackEvent } = useEventTracking()

// 追踪阅读素材事件
await trackEvent(EventType.READ_FILE, 'file-id-123')
</script>


带额外数据的埋点

<script setup>
import { useEventTracking, EventType } from '@/composables/useEventTracking'

const { trackEvent } = useEventTracking()

// 追踪阅读事件，并携带额外信息
await trackEvent(EventType.READ_FILE, 'file-id-123', {
  title: '保险产品手册',
  category: '产品资料',
  author: '张三'
})
</script>


使用便捷方法

<script setup>
import { useEventTracking } from '@/composables/useEventTracking'

const { trackFileRead } = useEventTracking()

// 便捷方法：追踪文件阅读
await trackFileRead('file-id-123', {
  title: '保险产品手册'
})
</script>


事件类型

当前支持的事件类型：


枚举值
说明
使用场景


EventType.READ_FILE
阅读素材
用户点击查看文件/素材时


未来可扩展的事件类型（已预留）：

EventType.COLLECT_FILE    // 收藏素材
EventType.SHARE_FILE      // 分享素材
EventType.DOWNLOAD_FILE   // 下载素材
EventType.VIEW_PRODUCT    // 查看产品


添加新的事件类型


1. 更新 EventType 枚举

编辑 src/composables/useEventTracking.js：

export const EventType = {
  READ_FILE: 'READ_FILE',
  // 添加新类型
  COLLECT_FILE: 'COLLECT_FILE',
}


2. 添加便捷方法（可选）

/**
 * 追踪收藏事件
 */
const trackFileCollect = async (fileId, extraData = {}) => {
  await trackEvent(EventType.COLLECT_FILE, fileId, extraData)
}

return {
  trackEvent,
  trackFileRead,
  trackFileCollect  // 导出新方法
}


最佳实践


✅ 推荐做法


使用枚举而非字符串
```javascript
// ✅ GOOD
await trackEvent(EventType.READ_FILE, fileId)


// ❌ BAD
   await trackEvent('READ_FILE', fileId)


2. **传递有意义的额外数据**
   ```javascript
   await trackEvent(EventType.READ_FILE, fileId, {
     title: '保险产品手册',
     category: '产品资料',
     format: 'PDF'
   })


埋点失败不影响用户体验
```javascript
// ✅ GOOD - 静默处理
try {
 await trackEvent(...)
} catch (error) {
 // 仅在开发环境记录
 if (process.env.NODE_ENV === 'development') {
   console.error('[埋点失败]', error)
 }
}


// ❌ BAD - 向用户显示错误
   try {
     await trackEvent(...)
   } catch (error) {
     Taro.showToast({ title: '埋点失败' })  // 不要这样做
   }


### ❌ 避免做法

1. **不要埋点阻塞用户操作**
   ```javascript
   // ❌ BAD - await 会阻塞
   const handleView = async () => {
     await trackEvent(...)  // 等待埋点完成
     navigateToDetail()     // 延迟跳转
   }

   // ✅ GOOD - 异步执行
   const handleView = () => {
     trackEvent(...)  // 不等待
     navigateToDetail()  // 立即执行
   }


不要在循环中批量发送埋点
```javascript
// ❌ BAD
items.forEach(item => {
 await trackEvent(...)  // 串行执行
})


// ✅ GOOD
   await Promise.all(items.map(item =>  // 并行执行
     trackEvent(...)
   ))


## 调试

### 开发环境日志

在开发环境中，埋点成功和失败都会输出日志：

```javascript
// 成功
[埋点成功] { type: 'READ_FILE', objectId: 'file-123', extraData: {...} }

// 失败
[埋点失败] Error: Request failed


验证埋点数据


打开微信开发者工具
切换到 "Network" 面板
触发埋点操作
查找 /srv/?a=event&t=add 请求
检查请求参数是否正确


常见问题


Q: 埋点失败会影响用户操作吗？

A: 不会。埋点失败会被静默处理，不会影响用户的正常操作流程。


Q: 如何查看埋点是否成功？

A:


开发环境查看控制台日志
使用微信开发者工具的 Network 面板查看请求
联系后端查看埋点数据


Q: 可以在组件卸载后继续埋点吗？

A: 不建议。埋点应该在组件生命周期内完成，避免潜在的内存泄漏。


Q: 埋点数据会持久化吗？

A: 埋点失败的数据不会重试，也不会持久化。如果需要离线埋点，需要额外的实现。


API 参考


useEventTracking()

返回对象：


属性
类型
说明


trackEvent
(type, objectId, extraData?) => Promise<void>
通用追踪方法


trackFileRead
(fileId, extraData?) => Promise<void>
文件阅读追踪


EventType

枚举值：


值
说明


READ_FILE
阅读素材


（未来扩展更多类型）


相关文档


API 接口文档
Composables 最佳实践