GA4 数据 API

使用此技能通过 OAuth 用户授权方式配置并查询 GA4。

默认方法

优先采用 OAuth 用户授权。

常规流程请使用 scripts/install_ga4_openclaw.sh + scripts/ga4_query.py。

仅在明确需要无头模式（headless）或服务端访问时，才建议后续使用 服务账号（service accounts）。

硬性规则

1. 配置前务必确认账号与权限

   • 需明确询问：哪个 Google 账号可实际登录 GA，并具备 GA4 属性（Property）或账号（Account）的访问权限？
   • 对于企业级/内部数据，默认不得直接启动服务账号配置流程。

2. 如实说明阻塞点

   • 若用户无法添加成员，请明确指出这是权限限制（permission blocker）。
   • 若 OAuth 应用仍处于“测试中（Testing）”状态，请说明必须将该账号添加为测试用户（test user）。
   • 若用户可见 GA4 属性但缺少管理员控制权限，请明确说明这是访问级别（access-level）问题，而非假装相关按钮被隐藏。

配置流程

步骤 1 — 确认访问模型

请询问或确认以下信息：

• 哪个 Google 账号拥有 GA 访问权限？
• 用户能否登录该账号？
• GA4 Property ID 是什么？
• Google Analytics Data API 是否已启用？
• 是否已存在桌面版 OAuth 客户端 JSON 文件（Desktop OAuth client JSON）？

步骤 2 — 安装并注入凭证

执行以下命令：

bash ~/.openclaw/workspace/skills/ga4-data-api/scripts/install_ga4_openclaw.sh  

该命令将完成以下操作：

• 安装 Python 依赖项；
• 将 OAuth 客户端 JSON 文件复制至 ~/.config/openclaw/ga4-client.json；
• 将 GA4_PROPERTY_ID 写入 shell 配置文件。

步骤 3 — 首次授权

执行以下命令：

python3 ~/.openclaw/workspace/skills/ga4-data-api/scripts/ga4_query.py 
  --metrics activeUsers,sessions 
  --dimensions date 
  --start 7daysAgo 
  --end today 
  --pretty

浏览器将自动打开。用户必须选择 真正拥有 GA 访问权限的那个 Google 账号 进行授权。

授权成功后将生成：

• ~/.config/openclaw/ga4-token.json

步骤 4 — 查询示例

近期趋势分析：

python3 ~/.openclaw/workspace/skills/ga4-data-api/scripts/ga4_query.py 
  --metrics activeUsers,sessions 
  --dimensions date 
  --start 7daysAgo 
  --end yesterday 
  --pretty

国家分布：

python3 ~/.openclaw/workspace/skills/ga4-data-api/scripts/ga4_query.py 
  --metrics activeUsers 
  --dimensions country 
  --start 7daysAgo 
  --end yesterday 
  --limit 50 
  --pretty

流量来源分布：

python3 ~/.openclaw/workspace/skills/ga4-data-api/scripts/ga4_query.py 
  --metrics sessions 
  --dimensions sessionSourceMedium 
  --start 7daysAgo 
  --end yesterday 
  --limit 50 
  --pretty

分析指导原则

针对趋势类问题：

• 除非用户明确要求按小时粒度分析，否则应优先使用完整自然日（例如 end=yesterday）；
• 若观察到当日数据下降，需主动说明这可能仅为部分时段数据（partial-day data），而非真实趋势变化。

针对转化类问题：

• 须严格区分 流量事件（traffic events） 与 真实转化事件（true conversion events）；
• 若关键事件定义过于宽泛，请建议先收窄事件集合，再基于此得出产品层面结论。

参考文档

• 当用户需要可复用、可共享的标准配置流程时，请查阅 references/setup.md；
• 请始终使用 scripts/ga4_query.py，避免每次手动编写全新的 GA SDK 示例代码。