数据埋点功能使用指南

本页面演示了如何在VitePress网站中集成点击数据埋点功能。

基础使用

自动埋点

给任何元素添加 data-analytics 属性，即可自动实现点击埋点：

<button data-analytics>点击我</button>
<a href="#" data-analytics>链接点击</a>

带标识的埋点

使用 data-analytics-id 属性指定元素ID：

<button data-analytics data-analytics-id="hero-cta">立即开始</button>

分类和标签

使用数据属性添加更多上下文信息：

<button 
  data-analytics 
  data-analytics-id="nav-home"
  data-analytics-category="navigation"
  data-analytics-label="首页导航">
  首页
</button>

高级使用

手动触发埋点

你也可以在JavaScript中手动触发埋点：

import { trackClick, trackPageView, trackCustomEvent } from './analytics'

// 点击埋点
await trackClick('custom-button', 'button')

// 页面访问埋点
await trackPageView('/guide/analytics')

// 自定义事件埋点
await trackCustomEvent('video_play', {
  element_id: 'demo-video',
  element_type: 'video'
})

埋点数据说明

每次点击都会上报以下数据：

字段	说明	示例
ip_address	客户端IP地址	192.168.1.100
access_path	访问路径	/guide/analytics.html
user_agent	用户代理	Mozilla/5.0...
element_id	元素ID	demo-button
element_type	元素类型	button
event_type	事件类型	click
device_type	设备类型	desktop
browser	浏览器类型	Chrome
os	操作系统	Windows 10
session_id	会话ID	sess_123456...
country	分类信息（复用字段）	navigation
city	标签信息（复用字段）	首页导航

测试功能

点击下方按钮测试不同的埋点场景：

浏览器控制台

打开浏览器控制台，你可以看到埋点发送的详细日志信息，包括：

• 发送的数据内容
• API响应结果
• 错误信息（如果有）

注意事项

1. 隐私保护: 埋点功能遵循隐私保护原则，不收集敏感个人信息
2. 性能优化: 埋点请求是异步的，不会影响页面性能
3. 错误处理: 即使埋点失败，也不会影响用户的正常操作
4. 会话管理: 使用sessionStorage管理会话ID，刷新页面后会保持同一会话

CORS跨域问题解决方案

由于浏览器安全策略，从本地开发环境（http://localhost:5173）向你的API服务器发送请求会遇到CORS限制。本实现提供了多种解决方案：

1. 图片像素跟踪（默认方案）

当直接POST请求失败时，会自动切换到图片像素跟踪模式：

• 将数据编码到图片URL参数中
• 使用new Image()发送请求，不受CORS限制
• 自动处理成功和失败情况

2. 服务器端CORS配置（推荐）

在你的Cloudflare Worker代码中添加CORS头：

// 在你的Worker代码中添加
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  // 处理CORS预检请求
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      status: 204,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'POST, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type',
        'Access-Control-Max-Age': '86400',
      },
    })
  }
  
  // 处理实际请求...
  const response = await yourActualHandler(request)
  
  // 添加CORS头
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'POST, OPTIONS')
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type')
  
  return response
}

3. 开发环境代理

在开发环境中，你可以使用Vite的代理配置：

测试验证

1. 打开浏览器控制台查看埋点日志
2. 点击页面上的测试按钮
3. 观察网络请求：
   • 首先尝试直接POST请求（可能因CORS失败）
   • 然后自动切换到图片像素跟踪
   • 控制台会显示详细的调试信息

常见问题

Q: 为什么埋点数据没有发送到服务器？

A: 检查浏览器控制台的网络请求，确认是否使用了图片像素跟踪模式。如果API服务器支持CORS，直接POST请求会自动生效。

Q: 如何确认数据是否成功接收？

A: 查看控制台日志，会显示发送方式和结果。图片像素跟踪模式会返回模拟的成功响应。

Q: 生产环境是否会有CORS问题？

A: 如果前端和后端部署在同一个域名下，不会有CORS问题。如果跨域，建议在服务器端配置CORS头。

实现原理

埋点功能通过以下技术实现：

1. 事件监听: 自动为带有 data-analytics 属性的元素添加点击事件监听
2. 数据收集: 收集点击元素的信息、用户设备信息、访问路径等
3. 异步发送: 使用Fetch API异步发送数据到后端API
4. 错误处理: 完善的错误处理机制，确保功能稳定性

这个功能可以帮助你更好地了解用户在网站上的行为，为优化用户体验提供数据支持。