portaly-analytics

Portaly 分析集成

使用此技能帮助 Portaly 创作者在网站上安装 Google Analytics 4，并将其连接到 Portaly。回答时应注重实操：优先提供步骤列表、代码片段和可直接复制的示例，而不是冗长的架构说明。

快速开始

• 首先询问用户想要完成什么：
  • 在我的网站上安装 GA4 → A 部分（步骤 1–5）
  • 将 GA 连接到 Portaly 控制面板 → B 部分（步骤 6）
  • 两者都要 → A 部分 + B 部分（步骤 1–6）

1. 确认用户正在尝试构建什么。 询问他们使用的技术栈（Next.js / React / vanilla HTML），以及是否已有 GA4 媒体资源。
2. 指导用户完成 GA4 设置和事件跟踪安装。
3. 如果用户想在 Portaly 中查看分析数据，指导其完成 Portaly 授权流程。
4. 从 references/ga4-setup-guide.md 开始查看安装说明。
5. 提供可直接用于实现的内容。 优先使用编号步骤、代码示例和可直接复制的配置。

输出风格

• 面向协助用户完成集成工作的 AI Agent 撰写。
• 首先说明用户接下来应采取的具体步骤。
• 以下内容使用列表：
  • 设置步骤
  • 环境变量
  • 事件定义
  • 配置选项
• 如果用户没有指定其他技术栈，优先提供简洁的 JavaScript 或 TypeScript 代码示例。
• 始终包含 .env 配置和 .gitignore 验证步骤。

A 部分 — GA4 安装和事件跟踪

1. 创建 GA4 媒体资源

• 如果用户还没有 GA4 媒体资源，指导他们创建：
  1. 前往 Google Analytics
  2. 点击“管理” → “创建媒体资源”
  3. 输入媒体资源名称，并选择时区和货币
  4. 使用网站 URL 设置 Web 数据流
  5. 复制衡量 ID（G-XXXXXXX）
• 请用户提供其衡量 ID。
• 将其保存到 .env：

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXX

• 继续之前，确认 .gitignore 中包含 .env。

2. 安装 gtag.js

• 参阅 references/ga4-setup-guide.md，了解针对不同框架的安装说明。
• 根据用户的技术栈选择正确的方式：
  • Next.js App Router → 使用 next/script 的 layout.tsx
  • Next.js Pages Router → 使用 next/script 的 _app.js
  • React SPA → index.html 脚本标签
  • Vanilla HTML → <head> 脚本标签
• 参考实现：scripts/gtag-nextjs-example.mjs

3. 设置 Portaly 事件跟踪

• 参阅 references/event-tracking-contract.md，了解标准 Portaly 事件定义。
• 根据用户应用的功能，安装标准 Portaly 事件：
  • portaly_checkout_start — 创建结账会话时
  • portaly_checkout_complete — 支付回调确认完成时
  • portaly_subscription_cancel — 取消订阅时
  • portaly_page_view — 查看嵌入 Portaly 的页面时
  • portaly_product_view — 查看产品页面时
• 在适用情况下，映射到 GA4 推荐的电子商务事件（begin_checkout、purchase）。
• 参考实现：scripts/track-portaly-events.mjs

4. 验证安装

• 指导用户在 GA4 实时报告中验证：
  1. 在浏览器中打开网站
  2. 前往 Google Analytics → 报告 → 实时
  3. 确认页面浏览和事件均已显示
• 如果事件没有显示，请检查：
  • 衡量 ID 是否正确
  • gtag.js 脚本是否已加载（检查浏览器的 Network 标签页）
  • 是否有广告拦截器造成干扰
  • 同意模式是否阻止了数据收集（如适用）

5. 可选：增强型电子商务跟踪

• 对于使用 Portaly 支付集成的用户，设置增强型电子商务事件：
  • view_item → 查看套餐或产品页面时
  • begin_checkout → 映射自 portaly_checkout_start
  • purchase → 映射自 portaly_checkout_complete
• 这些事件可启用 GA4 内置的电子商务报告。

B 部分 — 将 Google Analytics 连接到 Portaly

6. 授权 Portaly 访问 GA 数据

安装 GA4 并开始收集数据后，引导用户将其连接到 Portaly：

1. 前往 Portaly Vibe Dashboard：https://portaly.ai/dashboard/analytics
2. 前往 數據分析（Analytics）设置
3. 点击 連結 Google Analytics
4. 使用拥有 GA4 Property 的 Google 账号登录
5. 授予 Portaly 对 Google Analytics 数据的只读访问权限
6. 完成 — 分析仪表板将显示在 Portaly Vibe Dashboard 中

需要向用户说明的要点：

• Portaly 只会请求只读访问权限（analytics.readonly 范围）。Portaly 无法修改您的 GA4 设置或数据。
• 您可以随时在Google 账号权限中撤销访问权限。
• Portaly 中的仪表板将显示已连接 GA4 Property 的数据，包括会话数、网页浏览量、流量来源和 Portaly 专属事件。
• GA4 数据的处理延迟为 24–48 小时。新安装的跟踪可能需要 1–2 天才能在 Portaly 中显示历史数据。

防护措施

• Measurement ID 格式：始终为 G-XXXXXXX。如果用户提供了其他格式（例如 UA-XXXXX），那是 Universal Analytics ID — 请引导他们改为创建 GA4 Property。
• 凭据安全：Measurement ID（G-XXXXXXX）不是机密信息 — 它会显示在页面源代码中。不过，请始终将其存储在 .env 中以便于配置管理，并确认 .gitignore 包含 .env。
• 跨域跟踪：如果用户的应用会跳转到 portaly.ai 进行结账并返回，建议在 GA4 中设置跨域跟踪，以保持会话连续性：
  1. 前往 GA4 Admin → Data Streams → Web → Configure tag settings → Configure your domains
  2. 添加两个域名
• 广告拦截器：部分访客会使用拦截 gtag.js 的广告拦截器。GA4 数据始终会偏低。不要承诺 100% 的跟踪准确率。
• 同意模式：如果用户的网站需要征得 Cookie 同意（GDPR 等），请引导他们实施 GA4 同意模式。
• 数据时效性：GA4 数据的处理延迟为 24–48 小时。实时数据可在 GA4 自带的 Realtime 报告中查看，但 Portaly 仪表板依赖处理后的数据。
• Portaly 授权：Portaly OAuth 连接完全由 Portaly 托管的授权流程处理。用户无需创建任何 Google Cloud 项目或 OAuth 客户端，也无需管理 API 密钥。只需点击“连接”并授权即可。

推荐的回复结构

使用此技能回答时，建议按以下顺序组织：

1. 目标概述
2. 前提条件检查
3. 分步设置说明
4. 环境变量配置
5. 代码实现
6. 验证步骤
7. 故障排除说明

资源

• references/ga4-setup-guide.md 查看针对特定框架的 gtag.js 安装说明，以及页面浏览和事件跟踪设置。
• references/event-tracking-contract.md 查看 Portaly 标准事件名称、参数和 GA4 电商事件映射。
• scripts/gtag-nextjs-example.mjs 用于在 Next.js 应用中安装 gtag.js 的参考实现。
• scripts/track-portaly-events.mjs 用于跟踪 Portaly 专属事件的参考实现。