分析集成

Sistine Starter 支持多个分析平台，帮助你了解用户行为、性能指标和转化漏斗。

支持的分析工具

1. Google Analytics (GA4)

最流行的分析工具，提供详细的用户行为追踪

设置步骤:

访问 Google Analytics
创建新属性
获取 Measurement ID (格式: G-XXXXXXXXXX)
添加到 .env.local:

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

实现:

// components/analytics/google-analytics.tsx
'use client';

import Script from 'next/script';

export default function GoogleAnalytics() {
  const gaId = process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID;

  if (!gaId) return null;

  return (
    <>
      <Script
        src={`https://www.googletagmanager.com/gtag/js?id=${gaId}`}
        strategy="afterInteractive"
      />
      <Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', '${gaId}', { anonymize_ip: true });
        `}
      </Script>
    </>
  );
}

有用的事件:

// 跟踪自定义事件
gtag('event', 'generate_image', {
  'image_type': 'illustration',
  'credits_used': 20,
});

gtag('event', 'purchase', {
  'value': 99.99,
  'currency': 'USD',
  'items': [{ 'item_id': 'starter_plan' }],
});

2. Microsoft Clarity

提供会话录制和热力图分析

设置步骤:

访问 Microsoft Clarity
创建项目
获取 Project ID
添加到 .env.local:

NEXT_PUBLIC_CLARITY_PROJECT_ID=your_project_id

实现:

// components/analytics/clarity-analytics.tsx
'use client';

import Script from 'next/script';

export default function ClarityAnalytics() {
  const clarityId = process.env.NEXT_PUBLIC_CLARITY_PROJECT_ID;

  if (!clarityId) return null;

  return (
    <Script id="microsoft-clarity" strategy="afterInteractive">
      {`
        (function(c,l,a,r,i,t,y){
          c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
          t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
          y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
        })(window, document, "clarity", "script", "${clarityId}");
      `}
    </Script>
  );
}

3. PostHog

开源产品分析，支持自托管

设置步骤:

访问 PostHog
创建项目
获取 API Key 和 Host
添加到 .env.local:

NEXT_PUBLIC_POSTHOG_KEY=phc_your_key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

实现:

// lib/posthog.ts
import posthog from 'posthog-js';

export function initPostHog() {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    loaded: (ph) => {
      if (process.env.NODE_ENV === 'development') ph.debug();
    }
  });
}

// 在 app/layout.tsx 中调用

跟踪事件:

import posthog from 'posthog-js';

posthog.capture('image_generated', {
  image_type: 'illustration',
  model: 'doubao-seededit',
  credits_used: 20,
});

posthog.capture('subscription_created', {
  plan: 'pro_yearly',
  price: 990,
});

在应用中集成

1. 创建分析组件

components/analytics/analytics.tsx:

'use client';

import GoogleAnalytics from './google-analytics';
import ClarityAnalytics from './clarity-analytics';

export function Analytics() {
  // 在开发环境中禁用 (可配置)
  if (
    process.env.NODE_ENV !== 'production' &&
    !process.env.NEXT_PUBLIC_ANALYTICS_ENABLE_IN_DEVELOPMENT
  ) {
    return null;
  }

  return (
    <>
      <GoogleAnalytics />
      <ClarityAnalytics />
    </>
  );
}

2. 在主布局中注入

app/[locale]/layout.tsx:

import { Analytics } from '@/components/analytics/analytics';

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

3. 跟踪用户操作

'use client';

import { useEffect } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';

export function AnalyticsListener() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    // 页面视图跟踪
    const url = `${pathname}?${searchParams}`;

    // Google Analytics
    if (typeof window !== 'undefined' && window.gtag) {
      window.gtag('config', process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID, {
        page_path: url,
      });
    }
  }, [pathname, searchParams]);

  return null;
}

关键指标

用户行为指标

// AI 功能使用
gtag('event', 'ai_feature_used', {
  feature: 'chat',         // 或 'image', 'video'
  credits_cost: 10,
  duration_seconds: 45,
});

// 订阅事件
gtag('event', 'subscription_started', {
  plan: 'pro_monthly',
  price: 99.99,
});

gtag('event', 'subscription_canceled', {
  plan: 'pro_monthly',
  cancellation_reason: 'too_expensive',
});

// 错误追踪
gtag('event', 'exception', {
  description: 'API call failed',
  fatal: false,
});

转化漏斗

// 定价页面浏览
gtag('event', 'view_item', {
  items: [{ item_id: 'pricing_page', item_category: 'conversion' }],
});

// 开始结账
gtag('event', 'begin_checkout', {
  value: 99.99,
  currency: 'USD',
  items: [{ item_id: 'pro_plan' }],
});

// 购买完成
gtag('event', 'purchase', {
  transaction_id: 'T_123456',
  value: 99.99,
  currency: 'USD',
  items: [{ item_id: 'pro_plan', quantity: 1 }],
});

隐私和合规

在放置分析脚本前获取用户同意：

'use client';

import { useState, useEffect } from 'react';

export function CookieConsent() {
  const [showConsent, setShowConsent] = useState(false);

  useEffect(() => {
    const hasConsent = localStorage.getItem('analytics-consent');
    if (!hasConsent) {
      setShowConsent(true);
    }
  }, []);

  const handleAccept = () => {
    localStorage.setItem('analytics-consent', 'accepted');
    // 加载分析脚本
    window.location.reload();
  };

  if (!showConsent) return null;

  return (
    <div className="fixed bottom-0 left-0 right-0 bg-primary text-primary-foreground p-4">
      <p className="mb-4">我们使用分析工具来改进用户体验。</p>
      <div className="flex gap-4">
        <button onClick={handleAccept} className="px-4 py-2 bg-white text-primary rounded">
          接受
        </button>
        <button onClick={() => setShowConsent(false)} className="px-4 py-2 border border-white rounded">
          拒绝
        </button>
      </div>
    </div>
  );
}

2. IP 匿名化

// Google Analytics - 自动匿名化 IP
gtag('config', GA_ID, {
  anonymize_ip: true,
});

// 不发送 PII (个人可识别信息)
// ❌ 不要发送
gtag('event', 'purchase', {
  user_email: 'user@example.com',  // PII
  user_name: 'John Doe',           // PII
});

// ✅ 正确做法
gtag('event', 'purchase', {
  user_id: 'hashed_user_id',  // 哈希后的 ID
});

// 允许用户选择退出
export function OptOutAnalytics() {
  const handleOptOut = () => {
    // Google Analytics 退出
    window['ga-disable-GA_ID'] = true;

    // PostHog 退出
    if (window.posthog) {
      window.posthog.opt_out_capturing();
    }
  };

  return (
    <button onClick={handleOptOut}>
      退出分析追踪
    </button>
  );
}

常见问题

1. 分析脚本未触发

原因:

环境变量未设置
脚本加载策略不适当
广告拦截器

解决:

# 检查环境变量
echo $NEXT_PUBLIC_GOOGLE_ANALYTICS_ID

# 禁用广告拦截器后重试
# 检查浏览器控制台是否有错误

2. 数据不显示

原因:

数据传输中，需要等待 24 小时
跟踪 ID 不匹配
脚本未正确集成

解决:

// 在控制台验证数据是否发送
window.gtag('event', 'test_event');

// 检查 Network 标签中的请求
// 应该看到发往 Google Analytics 的请求

3. PostHog 事件未记录

原因:

API Key 无效
Host URL 不正确
用户选择退出

解决:

// 检查 PostHog 是否初始化
console.log(window.posthog);

// 验证配置
posthog.config?.api_host

最佳实践

1. 区分环境

// .env.local (开发环境)
NEXT_PUBLIC_ANALYTICS_ENABLE_IN_DEVELOPMENT=false

// .env.production (生产环境)
NEXT_PUBLIC_ANALYTICS_ENABLE_IN_DEVELOPMENT=false
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXX
NEXT_PUBLIC_CLARITY_PROJECT_ID=xxx

2. 避免重复追踪

// ❌ 避免多次调用
gtag('config', GA_ID);
gtag('config', GA_ID);  // 重复

// ✅ 在一个地方配置
if (typeof window !== 'undefined') {
  gtag('config', GA_ID);
}

3. 有意义的事件名称

// ❌ 不清晰
gtag('event', 'click');
gtag('event', 'submit');

// ✅ 清晰有意义
gtag('event', 'image_generation_started');
gtag('event', 'payment_form_submitted');
gtag('event', 'subscription_upgrade_clicked');

4. 分段用户

// 为不同用户类型设置用户属性
gtag('set', {
  'user_type': user.role,     // 'free', 'pro', 'admin'
  'plan': user.planKey,
  'registration_date': user.createdAt,
});

部署清单

下一步

部署指南 - 部署到生产
项目结构 - 代码组织
主题系统 - UI 自定义

分析集成

On this page