需要拉取 GA4 网站流量、渠道、转化与受众数据时用…

通过 Google Analytics Data API 查询 GA4 的流量、获客、页面、互动、转化和受众分群数据并生成报表。

适用场景

解决思路

1. 准备 Google OAuth 凭据：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和有效的 OAuth access token（按需刷新），将凭据写入 .env、.env.local 或 ~/.claude/.env.global。
2. 获取授权码：让用户在浏览器访问 https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/analytics.readonly&response_type=code&access_type=offline
3. 用授权码换取 token：curl -s -X POST "https://oauth2.googleapis.com/token" -d "code={AUTH_CODE}" -d "client_id=${GOOGLE_CLIENT_ID}" -d "client_secret=${GOOGLE_CLIENT_SECRET}" -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" -d "grant_type=authorization_code"
4. 刷新过期 token：curl -s -X POST "https://oauth2.googleapis.com/token" -d "refresh_token={REFRESH_TOKEN}" -d "client_id=${GOOGLE_CLIENT_ID}" -d "client_secret=${GOOGLE_CLIENT_SECRET}" -d "grant_type=refresh_token"；安全保存 refresh token，access token 1 小时后过期。
5. 查找 GA4 Property ID：curl -s -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" "https://analyticsadmin.googleapis.com/v1beta/accountSummaries" 并用 python3 解析 accountSummaries 中的 propertySummaries，输出 property、displayName 和 account displayName；property ID 格式为 properties/XXXXXXXXX。
6. 所有报表请求统一使用 POST https://analyticsdata.googleapis.com/v1beta/{property_id}:runReport，JSON body，并始终带 Authorization: Bearer {ACCESS_TOKEN}。
7. 流量总览报表：dateRanges 用 {"startDate": "30daysAgo", "endDate": "today"}，metrics 包含 sessions、totalUsers、newUsers、screenPageViews、engagementRate、averageSessionDuration、bounceRate。
8. 日期范围可用 today、yesterday、7daysAgo、14daysAgo、28daysAgo、30daysAgo、90daysAgo 或具体日期如 2024-01-01；传入两个 dateRanges 即可对比两个周期。
9. 用户获客报表：dimensions 用 sessionDefaultChannelGroup，metrics 用 sessions、totalUsers、engagementRate、conversions，orderBys 按 sessions 降序，limit 20。
10. 常用获客维度：sessionDefaultChannelGroup（渠道分组）、sessionSource（来源）、sessionMedium（媒介）、sessionCampaignName（UTM 活动名）、firstUserSource（首次触达来源）。
11. 热门页面报表：dimensions 用 pagePath，metrics 用 screenPageViews、totalUsers、engagementRate、averageSessionDuration，orderBys 按 screenPageViews 降序，limit 25。
12. 互动指标报表：dimensions 用 pagePath，metrics 用 engagedSessions、engagementRate、averageSessionDuration、screenPageViewsPerSession、eventCount，orderBys 按 engagedSessions 降序，limit 20。
13. 关键互动指标含义：engagementRate 为有互动会话占比（>10 秒、2+ 页面或转化）、averageSessionDuration 为平均会话秒数、screenPageViewsPerSession 为每会话页面数、bounceRate 为无互动会话占比、eventCount 为事件总数。
14. 转化跟踪报表：dimensions 用 eventName，metrics 用 eventCount、totalUsers、eventValue，并用 dimensionFilter 的 inListFilter 过滤 eventName 为 purchase、sign_up、generate_lead、begin_checkout 等。
15. 按渠道看转化：dimensions 用 sessionDefaultChannelGroup，metrics 用 sessions、conversions、totalRevenue，orderBys 按 conversions 降序。
16. 受众分群按设备：dimensions 用 deviceCategory，metrics 用 sessions、totalUsers、engagementRate、conversions。
17. 受众分群按国家：把 dimensions 中的 deviceCategory 替换为 country。
18. 按落地页 +# 来源分群：dimensions 用 landingPage 和 sessionSource，metrics 用 sessions、engagementRate、conversions，orderBys 按 sessions 降序，limit 30。
19. 周期对比：dateRanges 传两个对象，如 {"startDate": "30daysAgo", "endDate": "today", "name": "current"} 和 {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}，metrics 用 sessions、totalUsers、conversions、engagementRate。
20. 解析响应：用 python3 或 jq 读取 dimensionHeaders 和 metricHeaders 作为表头，遍历 rows 中的 dimensionValues 和 metricValues 输出表格。
21. 生成月度报表工作流：依次拉取带周期对比的流量总览、按渠道的获客拆分、按页面浏览量的 Top 20 页面、按渠道的转化汇总、设备与国家拆分，然后以结构化报告呈现表格、趋势（升降箭头）和建议。
22. 处理常见问题：403 Forbidden 表示用户无该 GA4 property 权限；空 rows 表示该日期范围或过滤条件无数据；Quota exceeded 表示超出每日配额，需缩短日期范围或批量请求；Property not found 需检查 property ID 格式是否为 properties/XXXXXXXXX。

适用边界 · 注意事项

• 没有 Google OAuth 凭据或无法完成 OAuth 授权流程时无法使用。
• 目标 GA4 property 未授予当前账号访问权限时无法拉取数据。
• 超出 GA4 API 每日配额时需减少请求或缩短日期范围，否则会失败。