文章

web-sveltekit 的 Analytics 支持

说明 web-sveltekit 如何接入 GA4、Plausible 和 Clarity，以及 consent 门控。

web-sveltekit 支持从 zship.app.json 配置可选的 analytics provider。

支持的 provider

Google Analytics 4，通过 analytics.googleAnalytics.measurementId
Plausible，通过 analytics.plausible.domain
Microsoft Clarity，通过 analytics.clarity.projectId

第三方 analytics 脚本默认不会注入。当至少配置了一个 provider，且 analytics.consentBanner.enabled 为 true 时，应用会展示 consent banner，并在用户做出选择后才加载对应脚本。

Consent 通过 cookie（zship_analytics_consent）与 localStorage 持久化
客户端工具位于 src/lib/client/analytics.ts（setAnalyticsConsent、trackAnalyticsEvent、trackAnalyticsPageView）
Banner UI 为 src/lib/components/AnalyticsConsentBanner.svelte
后续可在同一层扩展区域化 consent 或第一方代理

{
  "analytics": {
    "consentBanner": {
      "enabled": true
    },
    "googleAnalytics": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "plausible": {
      "domain": "sveltekit.zship.ai",
      "scriptSrc": "",
      "apiEndpoint": ""
    },
    "clarity": {
      "projectId": "your-clarity-project-id"
    }
  }
}

模板中请保持 provider ID 为空，直到你准备好上线统计。空 ID 意味着不加载脚本、也不展示 banner。

后续改进路径

如果生产环境需要更严格的合规控制，建议继续补上专门的 consent center，或走第一方代理后再启用 provider ID。

支持的 provider

Consent 流程

后续改进路径