如何使用Firebase Admin API结合Node.js SDK获取Firebase Analytics报告

嘿，我来帮你搞定这个需求——其实得先说明下：Firebase Admin SDK本身并没有直接提供查询Analytics数据的接口，不过因为Firebase Analytics现在和Google Analytics 4（GA4）深度绑定了，我们可以借助Google的Analytics Admin API和Analytics Data API来实现目标。下面是一步步的实操方案：

一、准备工作 #

1. 启用必要的API
   登录Google Cloud控制台（和你的Firebase项目关联的那个），找到并启用这两个API：

   • Google Analytics Admin API
   • Google Analytics Data API

2. 获取服务账号密钥
   从Firebase控制台进入「项目设置」→「服务账号」，点击「生成新的私钥」，下载JSON格式的密钥文件，保存到你的Node.js项目目录里。

二、安装依赖包 #

在项目根目录执行命令安装所需的npm包：

npm install firebase-admin @google-analytics/data @google-analytics/admin

三、初始化客户端 #

先初始化Firebase Admin SDK，同时初始化用于操作GA4的Admin和Data客户端：

const admin = require('firebase-admin');
const { GoogleAnalyticsAdminServiceClient } = require('@google-analytics/admin');
const { BetaAnalyticsDataClient } = require('@google-analytics/data');

// 加载服务账号密钥
const serviceAccount = require('./path/to/your-service-account-key.json');

// 初始化Firebase Admin
admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
});

// 初始化GA4相关客户端
const analyticsAdminClient = new GoogleAnalyticsAdminServiceClient({
  credentials: serviceAccount
});

const analyticsDataClient = new BetaAnalyticsDataClient({
  credentials: serviceAccount
});

四、找到你的GA4属性ID #

Firebase Analytics的数据会同步到关联的GA4属性里，所以我们需要先获取这个属性的ID：

async function getGA4PropertyId() {
  // 列出当前账号下的所有GA4账号
  const [accounts] = await analyticsAdminClient.listAccounts();
  const targetAccount = accounts[0]; // 如果你有多个账号，可根据名称筛选

  // 列出该账号下的所有GA4属性
  const [properties] = await analyticsAdminClient.listProperties({
    parent: `accounts/${targetAccount.name.split('/')[1]}`
  });

  // 找到和Firebase关联的属性（通常名称包含你的Firebase项目名）
  const firebaseLinkedProperty = properties.find(prop => 
    prop.displayName.includes('你的Firebase项目名称')
  );

  if (!firebaseLinkedProperty) {
    throw new Error('未找到关联的GA4属性，请检查Firebase项目是否已启用Analytics');
  }

  // 提取属性ID（格式是properties/123456789，我们只需要数字部分）
  const propertyId = firebaseLinkedProperty.name.split('/')[1];
  console.log(`找到关联的GA4属性ID：${propertyId}`);
  return propertyId;
}

五、查询Analytics报告数据 #

拿到属性ID后，就可以调用Analytics Data API查询自定义报告了，比如获取最近7天的活跃用户和事件数：

async function fetchAnalyticsReport(propertyId) {
  const [response] = await analyticsDataClient.runReport({
    property: `properties/${propertyId}`,
    // 设置日期范围
    dateRanges: [{ startDate: '7daysAgo', endDate: 'today' }],
    // 设置维度（比如按日期分组）
    dimensions: [{ name: 'date' }],
    // 设置要统计的指标
    metrics: [
      { name: 'activeUsers' }, // 活跃用户数
      { name: 'eventCount' }   // 事件总数量
    ]
  });

  // 格式化输出报告数据
  console.log('\n=== Analytics报告 ===');
  response.rows.forEach(row => {
    console.log(
      `日期: ${row.dimensionValues[0].value} | 活跃用户: ${row.metricValues[0].value} | 事件数: ${row.metricValues[1].value}`
    );
  });
}

// 执行查询流程
getGA4PropertyId()
  .then(propertyId => fetchAnalyticsReport(propertyId))
  .catch(err => console.error('获取报告失败:', err));

六、关键注意事项 #

• 权限配置：确保你的服务账号在Google Cloud IAM中被赋予了Analytics Viewer或Analytics Editor角色，否则会出现权限不足的错误。
• 数据延迟：Firebase Analytics的常规数据会有24-48小时的延迟，如果需要实时数据，可以使用runRealtimeReport方法（对应实时数据API）。
• 配额限制：Google Analytics Data API有每日调用配额，免费版通常是10000次/天，超过会被限流，具体可在Google Cloud控制台的API配额页面查看。
• 指标维度规范：所有可用的指标和维度必须遵循GA4的命名规范，比如screenPageViews（页面浏览量）、userAgeBracket（用户年龄分段）等。

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