埋点功能使用指南

概述

项目提供了统一的事件埋点功能，通过 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  // 导出新方法
}

最佳实践

✅ 推荐做法

1. 使用枚举而非字符串 ```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'
   })

1. 埋点失败不影响用户体验 ```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()  // 立即执行
   }

1. 不要在循环中批量发送埋点 ```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

验证埋点数据

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

常见问题

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

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

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

A:

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

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

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

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

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

API 参考

useEventTracking()

返回对象：

属性	类型	说明
trackEvent	(type, objectId, extraData?) => Promise<void>	通用追踪方法
trackFileRead	(fileId, extraData?) => Promise<void>	文件阅读追踪

EventType

枚举值：

值	说明
READ_FILE	阅读素材
（未来扩展更多类型）

相关文档

• API 接口文档
• Composables 最佳实践