Add Analytics

核心用法

add-analytics 是一款专为现代前端框架设计的 GA4 自动化集成技能。用户仅需提供 Measurement ID（G-XXXXXXXXXX 格式），技能即可智能识别项目技术栈——覆盖 Next.js（App/Pages Router）、Nuxt 3、Astro、SvelteKit、Vue/React + Vite、Angular、Gatsby 等 10 余种主流方案，并自动生成对应的最优接入代码。

显著优点

1. 框架感知能力：通过配置文件优先级扫描（next.config.js → nuxt.config.js → astro.config.mjs 等），精准定位项目类型，避免人工判断失误。
2. 全场景覆盖：无论是服务端渲染（SSR）、静态站点生成（SSG）还是纯 HTML 项目，均提供经过官方推荐的 Script 注入策略（如 Next.js 的 afterInteractive）。
3. 模块化扩展：通过 --events、--consent、--debug 三大可选参数，灵活追加自定义事件追踪、GDPR/CCPA 合规的 Cookie 同意管理、以及开发调试模式。
4. TypeScript 原生支持：自动生成 gtag.d.ts 类型声明与框架适配的类型安全代码，消除 any 类型滥用。

潜在局限与风险

• 隐私合规依赖人工二次确认：虽然提供 consent 模式模板，但实际 Cookie Banner UI 与法律文案需用户自行实现，技能仅提供底层 API 封装。
• 环境变量管理：要求用户手动将 .env.local 加入 .gitignore，存在密钥误提交风险（技能会提示但无法强制阻止）。
• 广告拦截器盲区：约 25-40% 用户启用广告拦截，GA4 数据天然不完整，技能未内置服务端日志兜底方案。
• Universal Analytics 遗留问题：若用户误传 UA- ID，技能仅作警告提示，需用户手动前往 GA 后台创建 GA4 属性。

适合人群

• 追求效率的独立开发者与初创团队，需要快速上线数据埋点
• 多框架技术栈并存的工程团队，需统一 GA4 接入规范
• 对 GDPR/CCPA 有基础合规需求但不愿从零搭建的中型项目

常规风险提醒

• 数据主权：Google Analytics 数据传输至美国服务器，欧盟用户需额外配置 IP 匿名化或考虑替代方案（如 Plausible）
• 性能敏感场景：第三方脚本可能阻塞核心指标（INP/LCP），建议在 Web Worker 中加载或使用 Partytown 等优化方案
• 调试陷阱：--debug 模式仅注入客户端标记，仍需配合 GA Debugger 扩展与实时报告验证，不可仅凭控制台无报错判定成功

核心用法

add-analytics 是一个纯文档型 Skill，用于为任何前端项目快速配置 Google Analytics 4。用户只需提供 G-XXXXXXXXXX 格式的 Measurement ID，Skill 即可自动检测项目框架（Next.js、Nuxt、Astro、SvelteKit、React、Vue、Angular、Plain HTML 等），并输出对应框架的完整集成代码。

基础命令格式：

add-analytics <measurement-id> [--events] [--consent] [--debug]

• --events: 添加自定义事件追踪工具函数
• --consent: 集成 GDPR 合规的 Cookie 同意模式
• --debug: 启用开发调试模式

显著优点

1. 全框架覆盖：支持 10+ 种主流前端框架，包括 Next.js App/Pages Router、Nuxt 3、Astro、SvelteKit、Remix、Gatsby、Vite+React/Vue、Angular、CRA 及原生 HTML
2. 自动化检测：通过配置文件优先级扫描（next.config.js → nuxt.config.js → astro.config.mjs...）智能识别项目类型
3. 生产级代码：所有示例均遵循各框架最佳实践（如 Next.js 的 Script 组件、afterInteractive 策略、环境变量隔离）
4. 隐私合规内置：可选的 GDPR 同意模式实现，包含 analytics_storage/ad_storage 等细粒度权限控制，以及持久化 Cookie 管理
5. TypeScript 友好：提供完整的 gtag.d.ts 类型声明，包含 ConfigParams、EventParams、ConsentParams 等接口
6. 事件追踪生态：预置 15+ 常用事件函数（click、scroll、sign_up、login、purchase、search、share、form_submit、exception 等）

潜在缺点与局限性

1. 仅输出代码，不自动写入：Skill 生成代码片段供用户手动复制，不会自动修改项目文件
2. 依赖外部服务：必须连接 googletagmanager.com，用户需自行处理广告拦截器兼容
3. Universal Analytics 已废弃：若用户提供 UA- 旧版 ID，需手动创建 GA4 属性迁移
4. 框架版本敏感：Next.js App Router vs Pages Router、Nuxt 2 vs 3 的代码差异较大，需准确检测
5. 无实时验证：无法自动测试 Measurement ID 是否有效，需用户手动在 GA4 后台确认数据接收

适合人群

• 需要快速接入网站分析的个人开发者与初创团队
• 技术 PM 或全栈工程师评估多框架 GA4 集成方案
• 需满足 GDPR/CCPA 合规要求的国际化产品团队
• 希望统一团队内不同项目分析埋点规范的技术负责人

常规风险

• 隐私合规风险：未启用 --consent 时默认直接追踪，可能违反欧盟/加州法规
• 环境变量泄露风险：Measurement ID 若误提交至 Git 仓库（Skill 已提示添加 .gitignore）
• 数据采样失真：高流量站点需购买 GA4 360 以避免采样，免费版有每日事件数限制
• SPA 路由重复计数：部分框架示例需额外处理路由变化时的 pageview 去重