分析集成

ProductReady 内置支持 Google Analytics 和 Microsoft Clarity。这些集成经过精心设计，最小化配置，生产就绪，只需配置环境变量即可使用。

支持的分析平台

Google Analytics (GA4)

Google Analytics 帮助您了解用户行为、跟踪转化并衡量营销投资回报率。

功能：

• 📊 页面浏览跟踪
• 🎯 事件跟踪
• 👥 用户人口统计
• 📈 转化跟踪
• 🔍 实时分析

最适合：了解用户行为、营销归因和转化优化。

Microsoft Clarity

Microsoft Clarity 提供会话录制和热图，可视化用户如何与您的应用程序交互。

功能：

• 🎥 会话录制
• 🔥 热图（点击、滚动、区域）
• 📱 移动端和桌面端洞察
• ⚡ 性能指标
• 🆓 100% 免费（无限制）

最适合：用户体验优化、识别可用性问题和了解用户痛点。

快速开始

# Google Analytics（可选）
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-XXXXXXXXXX"

# Microsoft Clarity（可选）
NEXT_PUBLIC_CLARITY_PROJECT_ID="your-clarity-project-id"

pnpm dev

配置详情

Google Analytics

ProductReady 使用 Next.js 内置的 @next/third-parties/google 包以获得最佳性能。

主要功能：

• ✅ 兼容服务器端渲染
• ✅ 自动页面浏览跟踪（App Router）
• ✅ 性能优化（延迟加载）
• ✅ TypeScript 支持

组件位置：src/components/analytics/google-analytics.tsx

集成点：src/app/layout.tsx（根布局）

跟踪行为：

• 自动：每次路由更改时跟踪页面浏览
• 手动事件：使用 gtag() 函数进行自定义事件跟踪

自定义事件跟踪示例：

// 在任何客户端组件中
'use client';

import { useEffect } from 'react';

export function MyComponent() {
  const handleClick = () => {
    // 跟踪自定义事件
    if (typeof window !== 'undefined' && window.gtag) {
      window.gtag('event', 'button_click', {
        button_name: 'cta_button',
        page_path: window.location.pathname,
      });
    }
  };

  return <button onClick={handleClick}>点击我</button>;
}

TypeScript 支持：

// 添加到您的 global.d.ts 或 env.d.ts
interface Window {
  gtag: (
    command: 'config' | 'event' | 'set',
    targetId: string,
    config?: Record<string, unknown>
  ) => void;
}

Microsoft Clarity

Clarity 使用 Next.js 的 <Script> 组件集成，策略为 strategy="afterInteractive"。

主要功能：

• ✅ 会话录制
• ✅ 热图（点击、滚动、区域）
• ✅ 不影响页面加载性能
• ✅ 注重隐私（符合 GDPR）
• ✅ 永久免费

组件位置：src/components/analytics/microsoft-clarity.tsx

集成点：src/app/layout.tsx（根布局）

Clarity 跟踪内容：

• 鼠标移动和点击
• 滚动行为
• 愤怒点击（用户沮丧）
• 页面性能指标
• 无效点击（无效果的点击）

隐私和 GDPR 合规性

Google Analytics

收集的数据：

• IP 地址（可匿名化）
• 用户代理字符串
• 页面 URL
• 引荐来源信息
• 用户交互

GDPR 考虑因素：

• 启用 IP 匿名化：在 GA4 设置中添加 anonymize_ip: true
• 更新您的隐私政策
• 为欧盟用户考虑 Cookie 同意横幅
• 提供退出机制

IP 匿名化示例：

// 如需要，修改 google-analytics.tsx
import { GoogleAnalytics as NextGoogleAnalytics } from "@next/third-parties/google";

export const GoogleAnalytics = () => {
  const gaId = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
  if (!gaId) return null;

  return (
    <NextGoogleAnalytics 
      gaId={gaId}
      dataLayerName="dataLayer"
    />
  );
};

Microsoft Clarity

收集的数据：

• 会话录制（可视化表示）
• 鼠标移动
• 滚动深度
• 点击模式

GDPR 考虑因素：

• Clarity 自动屏蔽敏感数据（密码、信用卡）
• 可通过 Clarity 仪表板配置额外的屏蔽
• 默认情况下不存储个人身份信息 (PII)
• 更新隐私政策以提及会话录制

测试和调试

验证 Google Analytics

1. 实时报告：

• 转到 GA4 仪表板 → 报告 → 实时
• 在新标签页中打开您的应用程序
• 您应该会看到您的会话实时出现

2. 浏览器开发者工具：

// 检查 gtag 是否已加载（在浏览器控制台中）
console.log(typeof window.gtag); // 应输出 "function"

// 手动触发测试事件
window.gtag('event', 'test_event', { test: 'value' });

3. Chrome 扩展：

• 安装 Google Analytics Debugger
• 启用扩展
• 重新加载页面并检查控制台中的 GA 调试日志

验证 Microsoft Clarity

1. Clarity 仪表板：

• 访问 Clarity Dashboard
• 选择您的项目
• 检查"录制"选项卡（数据在几分钟内出现）

2. 浏览器开发者工具：

// 检查 Clarity 是否已加载（在浏览器控制台中）
console.log(typeof window.clarity); // 应输出 "function"

// 检查 Clarity 队列
console.log(window.clarity?.q);

3. 网络选项卡：

• 打开开发者工具 → 网络选项卡
• 按"clarity.ms"筛选
• 您应该会看到对 Clarity 跟踪端点的请求

环境特定配置

开发环境 vs 生产环境

开发环境（.env.local）：

# 可选：使用测试/开发跟踪 ID
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-DEV123TEST"
NEXT_PUBLIC_CLARITY_PROJECT_ID="devtestproject"

生产环境（Vercel/托管平台）：

# 使用生产跟踪 ID
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-PROD123REAL"
NEXT_PUBLIC_CLARITY_PROJECT_ID="prodproject"

条件加载

两个集成都会自动检查环境变量，并仅在存在 ID 时加载。无需额外配置！

// 内置行为（无需更改）
export const GoogleAnalytics = () => {
  const gaId = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
  if (!gaId) return null; // ✅ 未配置时不会加载
  return <NextGoogleAnalytics gaId={gaId} />;
};

性能影响

Google Analytics

• 脚本大小：~28KB gzip 压缩后
• 加载策略：页面交互后延迟加载
• 性能分数影响：Lighthouse 上 < 1 分
• 首次内容绘制 (FCP)：无影响
• 交互时间 (TTI)：最小（~50ms）

Microsoft Clarity

• 脚本大小：~45KB gzip 压缩后
• 加载策略：交互后（strategy="afterInteractive"）
• 性能分数影响：Lighthouse 上 < 2 分
• 首次内容绘制 (FCP)：无影响
• 交互时间 (TTI)：最小（~100ms）

高级用法

自定义事件跟踪 (GA4)

跟踪特定的用户操作：

'use client';

export function PricingCard() {
  const handlePurchase = (plan: string) => {
    // 跟踪购买意图
    window.gtag?.('event', 'begin_checkout', {
      currency: 'USD',
      value: 99.00,
      items: [{ item_id: plan, item_name: plan }],
    });
  };

  return <button onClick={() => handlePurchase('pro')}>购买专业版</button>;
}

Clarity 自定义标签

添加自定义标签以组织录制：

'use client';

import { useEffect } from 'react';

export function DashboardPage() {
  useEffect(() => {
    // 使用自定义元数据标记会话
    if (typeof window !== 'undefined' && window.clarity) {
      window.clarity('set', 'user_type', 'premium');
      window.clarity('set', 'feature', 'dashboard');
    }
  }, []);

  return <div>仪表板内容</div>;
}

故障排除

Google Analytics 无法工作

问题：GA4 仪表板中没有数据出现

解决方案：

1. ✅ 验证 NEXT_PUBLIC_GA_MEASUREMENT_ID 设置正确
2. ✅ 检查衡量 ID 格式：G-XXXXXXXXXX
3. ✅ 等待 24-48 小时获取初始数据（默认不是实时的）
4. ✅ 检查 GA4 → 管理 → 数据流 → 确保流处于活动状态
5. ✅ 验证网络选项卡中的请求：查找 google-analytics.com/g/collect

调试模式：

# 添加到 .env 以获取详细日志（仅限开发）
NEXT_PUBLIC_GA_DEBUG=true

Microsoft Clarity 未录制

问题：没有会话录制出现

解决方案：

1. ✅ 验证 NEXT_PUBLIC_CLARITY_PROJECT_ID 正确
2. ✅ 检查 Clarity 仪表板中的项目状态（必须处于活动状态）
3. ✅ 确保项目设置为正确的域
4. ✅ 禁用广告拦截器/隐私扩展（它们可能会阻止 Clarity）
5. ✅ 检查浏览器控制台是否有脚本错误

常见问题：

• 广告拦截器：隐私扩展可能会阻止 Clarity
• 内容安全策略：确保 script-src 允许 clarity.ms
• 同源错误：确保域与 Clarity 项目设置匹配

最佳实践

1. 每个环境使用单独的跟踪 ID

# .env.local（开发）
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-DEV123"

# .env.production（生产）
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-PROD456"

2. 隐私优先

• ✅ 在隐私政策中添加分析披露
• ✅ 为欧盟用户实施 Cookie 同意横幅
• ✅ 在 GA4 中启用 IP 匿名化
• ✅ 为敏感字段配置 Clarity 数据屏蔽

3. 监控性能

• ✅ 定期检查 Lighthouse 分数
• ✅ 使用 Next.js Analytics（Vercel）监控真实用户指标
• ✅ 监控核心 Web 指标影响

4. 生产前测试

• ✅ 首先在预发布环境中测试分析
• ✅ 验证事件跟踪按预期工作
• ✅ 检查两个平台是否正确接收数据

从其他分析平台迁移

从 Google Universal Analytics (UA) 迁移

步骤：

1. 在 Google Analytics 中创建新的 GA4 属性
2. 将 NEXT_PUBLIC_GA_MEASUREMENT_ID 更新为 GA4 衡量 ID（以 G- 开头）
3. 删除任何旧的 Universal Analytics 跟踪代码（以 UA- 开头）

从 PostHog 迁移

PostHog 已经支持！请参阅 .env.example：

NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"

您可以将 PostHog 与 GA 和 Clarity 一起使用。

添加其他分析平台

想要添加另一个分析平台？遵循这个模式：

// src/components/analytics/my-analytics.tsx
import Script from "next/script";

export const MyAnalytics = () => {
  const trackingId = process.env.NEXT_PUBLIC_MY_ANALYTICS_ID;
  if (!trackingId) return null;

  return (
    <Script
      id="my-analytics"
      strategy="afterInteractive"
      src={`https://example.com/script.js?id=${trackingId}`}
    />
  );
};

// src/components/analytics/index.ts
export { MyAnalytics } from "./my-analytics";

// src/app/layout.tsx
import { MyAnalytics } from "~/components/analytics";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <MyAnalytics />
      </body>
    </html>
  );
}

# My Analytics（可选）
# NEXT_PUBLIC_MY_ANALYTICS_ID="your-tracking-id"

延伸阅读

• Next.js 第三方库
• Google Analytics 4 文档
• Microsoft Clarity 文档
• GDPR 合规指南
• Web 分析最佳实践