将基于Google Analytics Embed API的仪表盘迁移至GA4方案咨询

由于Google Analytics Embed API不支持GA4属性，你需要切换到Google Analytics Data API（GA4专属的REST API）来实现数据读取。以下是针对你现有代码的迁移方案：

核心修改说明 #

1. 替换API库：放弃原gapi.analytics，改用gapi.client.analyticsdata（GA4 Data API的客户端库）
2. 调整身份验证：保持原有OAuth授权逻辑的前提下，确保权限覆盖GA4属性（scope仍为https://www.googleapis.com/auth/analytics.readonly）；若使用API Key，需在Google Cloud控制台为GA4 Data API启用密钥
3. 映射UA与GA4字段：
   • UA的ga:sessions → GA4的sessions指标
   • UA的ga:date → GA4的date维度
   • UA的ga:sessionsPerUser==1筛选 → GA4的sessionsPerUser指标筛选
4. 重构查询结构：GA4采用请求体（requestBody）方式定义查询，替代原Embed API的query对象
5. 适配响应格式：GA4返回的总数据结构与UA不同，需调整数据提取逻辑

迁移后的完整代码示例 #

// 初始化并加载GA4 Data API
gapi.load('client', async () => {
  await gapi.client.init({
    // 若使用OAuth授权，此处替换为你的客户端ID配置；若用API Key则填写apiKey
    clientId: 'YOUR_OAUTH_CLIENT_ID',
    scope: 'https://www.googleapis.com/auth/analytics.readonly',
    discoveryDocs: ['https://analyticsdata.googleapis.com/$discovery/rest?version=v1beta']
  });

  // 构造GA4查询请求
  const propertyId = Dashboard.getIds().replace('ga:', ''); // 需确保返回GA4的Property ID（如213456789）
  const response = await gapi.client.analyticsdata.properties.runReport({
    property: `properties/${propertyId}`,
    requestBody: {
      metrics: [{ name: 'sessions' }],
      dimensions: [{ name: 'date' }],
      dateRanges: [
        {
          startDate: Dashboard.getReportDateStart(),
          endDate: Dashboard.getReportDateEnd()
        }
      ],
      // 对应原UA的filters: 'ga:sessionsPerUser==1'
      metricFilter: {
        filter: {
          metricName: 'sessionsPerUser',
          stringFilter: {
            matchType: 'EXACT',
            value: '1'
          }
        }
      }
    }
  });

  // 提取总会话数并更新DOM
  const totalSessions = response.result.totals[0].values[0];
  $("#metric-users-unique").text(totalSessions);
  $("#metric-sessions-unique").text(totalSessions);
});

关键注意事项 #

• Property ID替换：原Dashboard.getIds()返回的是UA视图ID（格式ga:xxxxxx），需改为GA4的Property ID（纯数字，可在GA4后台查看），若无法修改getIds()方法，可通过字符串替换临时处理
• 异步逻辑调整：GA4 Data API采用Promise/async-await方式处理响应，替代原Embed API的事件监听模式
• 筛选条件适配：若原UA筛选涉及维度，需改用dimensionFilter而非metricFilter，具体可参考GA4 Data API的筛选规则
• 权限配置：确保你的OAuth客户端或API Key已在Google Cloud控制台启用Google Analytics Data API，并拥有目标GA4属性的读取权限

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