GA4嵌入式API调用转换及数据获取问题技术咨询

核心前提 #

Google Analytics嵌入式API（Embed API）仅支持UA（Universal Analytics），无GA4适配版本。2023年7月UA停止新数据收集后，它无法获取GA4后续数据，必须切换至Google Analytics Data API v1（原GA4 Reporting API）。

UA Embed API转GA4 Data API的关键映射 #

UA调用的核心要素（视图ID、指标、维度、日期范围）需对应转换为GA4格式：

• 资源标识：UA的viewId（如ga:12345678）替换为GA4的propertyId（格式为properties/XXXXXX，XXXXXX为GA4媒体资源ID）
• 指标映射：UA的ga:sessions→GA4sessions；ga:users→activeUsers；ga:pageviews→screenPageViews（GA4统一网页/APP的页面浏览指标）
• 维度映射：UA的ga:date→GA4date；ga:pagePath→pagePath；ga:country→country
• 日期范围：GA4用dateRanges数组定义，示例：{"startDate": "2023-07-01", "endDate": "today"}，替代UA的start-date/end-date参数

代码示例对比 #

UA Embed API调用（伪代码）：

gapi.analytics.report({
  query: {
    ids: 'ga:12345678',
    metrics: 'ga:sessions,ga:pageviews',
    dimensions: 'ga:date',
    'start-date': '2023-07-01',
    'end-date': 'today'
  }
});

对应GA4 Data API v1 REST请求：

POST https://analyticsdata.googleapis.com/v1beta/properties/12345678:runReport
{
  "dateRanges": [{"startDate": "2023-07-01", "endDate": "today"}],
  "metrics": [{"name": "sessions"}, {"name": "screenPageViews"}],
  "dimensions": [{"name": "date"}]
}

管理页面展示的适配方案 #

要实现类似UA Embed API的报表展示效果，可选以下路径：

• 自定义渲染：通过GA4 Data API获取原始数据，用前端图表库（Chart.js、ECharts等）自行绘制报表，完全适配管理页面样式
• Looker Studio嵌入：将GA4数据制作成Looker Studio仪表盘，直接嵌入管理页面，开箱即用，无需大量开发
• 封装API接口：后端封装GA4 Data API的调用逻辑，对外提供类似UA Embed API的简化接口，降低前端开发成本

常见问题解决 #

• 权限问题：确保服务账号/OAuth账号拥有GA4媒体资源的Analytics Viewer或Analytics Editor权限，且已完成资源关联
• 指标维度匹配：GA4指标维度无ga:前缀，部分名称与UA差异较大，需对照官方维度指标列表确认
• 数据延迟：GA4常规数据延迟24-48小时，若需实时数据，需使用GA4 Realtime API

内容的提问来源于stack exchange，提问作者Clubcodetown