Google Analytics 集成指南

Google Analytics 集成指南

本指南将帮助你在 PPage 个人主页项目中配置和使用 Google Analytics (GA4) 进行网站访问数据统计和分析。

功能特性

✅ 配置驱动：通过 config.yml 轻松配置，无需修改代码
✅ 环境区分：支持开发/生产环境独立控制
✅ 自动跟踪：自动跟踪页面浏览和路由变化
✅ 自定义事件：支持手动发送自定义事件
✅ 错误处理：完善的错误处理和环境检测
✅ 隐私友好：可选择在开发环境禁用跟踪

快速开始

1. 获取 Google Analytics 测量 ID

  1. 访问 Google Analytics
  2. 创建或选择一个媒体资源 (Property)
  3. 创建数据流 (Data Stream)，选择"网站"类型
  4. 复制测量 ID（格式：G-XXXXXXXXXX）

2. 配置 PPage

编辑项目根目录下的 public/config.yml 文件，添加或修改以下配置：

# Google Analytics 配置
analytics:
  # Google Analytics 测量ID（GA4）
  googleAnalytics: 'G-XXXXXXXXXX' # 替换为你的测量 ID

  # 是否在开发环境中启用（默认为 false）
  enableInDev: false # 开发环境不发送数据

3. 验证配置

启动开发服务器：

npm run dev

打开浏览器控制台，你应该看到类似的日志：

  • 如果配置了 GA ID：Google Analytics: 初始化成功 (G-XXXXXXXXXX)
  • 如果未配置：Google Analytics: 未配置测量ID，跳过初始化
  • 如果是开发环境且未启用：Google Analytics: 开发环境已禁用，跳过初始化

配置选项详解

googleAnalytics

  • 类型：String
  • 必填：否
  • 格式：G-XXXXXXXXXX（GA4 测量 ID）
  • 说明：你的 Google Analytics 测量 ID。留空则不启用 GA 跟踪

enableInDev

  • 类型：Boolean
  • 必填：否
  • 默认值：false
  • 说明：
    • true：开发环境（localhost）也会发送数据到 GA
    • false：只在生产环境（部署后）发送数据

自动跟踪功能

PPage 已自动集成以下跟踪功能：

页面浏览跟踪

每次路由变化时，自动发送页面浏览事件，包含：

  • 页面路径 (page_path)
  • 页面标题 (page_title)
  • 页面完整 URL (page_location)

文件下载跟踪

当用户点击下载按钮时，自动发送文件下载事件，包含：

  • 文件名称 (file_name)
  • 文件类型 (file_type)
  • 文件路径 (file_path)

自定义事件跟踪

你可以在组件中手动发送自定义事件。

基本用法

import { trackEvent } from '../components/analytics/GoogleAnalytics'

// 发送简单事件
trackEvent('button_click')

// 发送带参数的事件
trackEvent('contact_form_submit', {
  form_name: 'contact',
  user_type: 'visitor',
})

实际示例

跟踪按钮点击

import { trackEvent } from '../components/analytics/GoogleAnalytics'

function ContactButton() {
  const handleClick = () => {
    trackEvent('contact_click', {
      button_location: 'header',
      button_text: 'Contact Me',
    })
  }

  return <button onClick={handleClick}>Contact Me</button>
}

跟踪外部链接点击

import { trackEvent } from '../components/analytics/GoogleAnalytics'

function ExternalLink({ href, children }) {
  const handleClick = () => {
    trackEvent('outbound_link_click', {
      link_url: href,
      link_text: children,
    })
  }

  return (
    <a
      href={href}
      onClick={handleClick}
      target="_blank"
      rel="noopener noreferrer"
    >
      {children}
    </a>
  )
}

跟踪表单提交

import { trackEvent } from '../components/analytics/GoogleAnalytics'

function NewsletterForm() {
  const handleSubmit = e => {
    e.preventDefault()

    trackEvent('newsletter_signup', {
      form_location: 'footer',
      subscription_type: 'email',
    })

    // 继续处理表单提交...
  }

  return <form onSubmit={handleSubmit}>{/* 表单内容 */}</form>
}

在 Google Analytics 中查看数据

实时报告

  1. 登录 Google Analytics
  2. 选择你的媒体资源
  3. 点击左侧菜单的"实时" (Realtime)
  4. 你可以看到：
    • 当前在线用户数
    • 实时浏览的页面
    • 用户来源
    • 触发的事件

事件报告

  1. 点击左侧菜单的"报告" → “参与度” → “事件”
  2. 你可以看到所有自定义事件，例如：
    • page_view（页面浏览）
    • file_download（文件下载）
    • 你定义的自定义事件

页面和屏幕报告

  1. 点击左侧菜单的"报告" → “参与度” → “页面和屏幕”
  2. 查看：
    • 各页面的浏览量
    • 平均停留时间
    • 跳出率

环境检测逻辑

PPage 的 GA 组件会自动检测运行环境：

开发环境判断

满足以下任一条件视为开发环境：

  • hostname === 'localhost'
  • hostname === '127.0.0.1'
  • hostname === ''（空字符串）

生产环境

其他情况均视为生产环境（如部署在 GitHub Pages、自定义域名等）

控制逻辑

环境 enableInDev 是否发送数据
开发 false ❌ 否
开发 true ✅ 是
生产 false ✅ 是
生产 true ✅ 是

隐私和合规性

数据隐私

Google Analytics 会收集以下数据：

  • 页面浏览记录
  • 用户行为事件
  • 设备和浏览器信息
  • IP 地址（可配置匿名化）

合规建议

  1. 添加隐私政策：在你的网站上添加隐私政策页面，说明使用了 Google Analytics
  2. Cookie 通知：根据所在地区法规，可能需要添加 Cookie 同意横幅
  3. IP 匿名化：可以在 GA 后台启用 IP 地址匿名化
  4. 数据保留期限：在 GA 后台配置合理的数据保留期限

可选：添加隐私政策链接

在 config.yml 中添加隐私政策链接：

navigation:
  - name: '隐私政策'
    path: '/privacy'

然后创建 content/pages/privacy.md 文件说明你的隐私政策。

故障排查

GA 不工作？

检查以下几点：

  1. 测量 ID 格式正确吗？

    • 应该是 G-XXXXXXXXXX 格式
    • 检查配置文件中是否有拼写错误

  2. 配置文件路径正确吗？

    • 确保配置在 public/config.yml 文件中
    • 不是 config.example.yml

  3. 开发环境是否启用？

    • 如果在本地测试，需要设置 enableInDev: true

  4. 浏览器控制台有错误吗？

    • 打开开发者工具查看控制台
    • 查找 “Google Analytics” 相关的日志或错误

  5. 广告拦截器

    • 某些广告拦截器会阻止 GA 脚本
    • 尝试禁用广告拦截器测试

验证 GA 是否正常工作

  1. 检查控制台日志：

    Google Analytics: 初始化成功 (G-XXXXXXXXXX)
Google Analytics: 页面浏览跟踪 - /about

  2. 检查网络请求：

    • 打开开发者工具 → Network 标签
    • 过滤 google-analytics.com 或 googletagmanager.com
    • 应该能看到相关请求

  3. 使用 GA 实时报告：

    • 访问你的网站
    • 同时打开 GA 后台的实时报告
    • 应该能看到你的访问

性能优化

PPage 的 GA 集成已优化性能：

  1. 异步加载：GA 脚本异步加载，不阻塞页面渲染
  2. 延迟初始化：只在配置加载完成后初始化
  3. 条件加载：未配置时完全跳过，零开销
  4. 错误隔离：GA 错误不影响网站正常功能

最佳实践

1. 生产环境启用，开发环境禁用

analytics:
  googleAnalytics: 'G-XXXXXXXXXX'
  enableInDev: false # 开发时不发送垃圾数据

2. 使用有意义的事件名称

// ✅ 好的事件名
trackEvent('newsletter_signup', { source: 'footer' })
trackEvent('paper_download', { paper_title: 'My Research' })

// ❌ 避免的事件名
trackEvent('click')
trackEvent('event1')

3. 添加有用的事件参数

// ✅ 提供上下文信息
trackEvent('project_view', {
  project_name: 'PPage',
  project_category: 'web',
  view_source: 'featured',
})

// ❌ 参数过少
trackEvent('project_view')

4. 遵守隐私规定

  • 不跟踪敏感个人信息
  • 提供隐私政策
  • 考虑添加 Cookie 同意机制

相关资源

总结

通过本指南，你已经学会了：

  • ✅ 如何获取和配置 GA 测量 ID
  • ✅ 如何在 PPage 中启用 Google Analytics
  • ✅ 如何使用自动跟踪功能
  • ✅ 如何发送自定义事件
  • ✅ 如何在 GA 后台查看数据
  • ✅ 隐私合规性注意事项

现在你可以开始收集和分析你的网站访问数据了！🎉