向 Google Analytics（分析）发送 Measurement Protocol 事件

本指南介绍了如何将 Google Analytics Measurement Protocol 网站和应用数据流事件发送到 Google Analytics 服务器，以便在 Google Analytics 报告中查看 Measurement Protocol 事件。

Measurement Protocol 请求所需的标识符和参数取决于您是将事件发送到网站数据流还是应用数据流。

  • 对于网站数据流（通常使用 gtag.js 或 Google 跟踪代码管理器进行检测），您可以使用请求网址中的 measurement_id 和 JSON 正文中的 client_id 来识别用户实例。client_id应与网站上 Google Analytics 代码生成的 ID 一致。
  • 对于使用 Firebase SDK 检测的应用数据流，您可以使用请求网址中的 firebase_app_id 和 JSON 正文中的 app_instance_id，它们由 Google Analytics for Firebase SDK 提供。

本指南针对这两种情况提供了示例。

按视频流类型划分的关键请求组件

组件 网站数据流 (gtag.js/GTM) 应用数据流 (Firebase)
数据流网址参数 measurement_id firebase_app_id
API Secret 网址参数 必需 必需
设备 ID JSON 正文字段 client_id app_instance_id

请选择您想在本指南中查看哪个平台的信息：

此标签页显示了相关说明，介绍了如何使用 Google Analytics for Firebase SDK 从服务器发送与应用数据流中的用户活动相关的事件。请注意，这些请求使用 firebase_app_id 和 app_instance_id。

前提条件

如需使用 Measurement Protocol 发送事件，您需要 Google Analytics 媒体资源或 Firebase 项目中的特定标识符。

API 密钥

api_secret 用于对您的请求进行身份验证。务必对此密钥保密。

如需创建新的 Secret，请执行以下操作：

  1. 前往 Google Analytics，然后前往您的账号和媒体资源。
  2. 点击左下角的管理。
  3. 在数据收集和修改下方，点击数据流。
  4. 选择您的网站或应用数据流。
  5. 点击 Measurement Protocol API 密钥。
  6. 点击创建。
  7. 为密钥输入别名，然后点击创建。

  8. 复制 Secret 值。

Firebase 应用 ID

firebase_app_id 用于标识您的 Firebase 应用，与 app_instance_id 不同。

如需查找 Firebase 应用 ID，请执行以下操作：

  1. 在 Firebase 控制台中打开您的项目。
  2. 点击项目概览旁边的设置齿轮图标，然后选择项目设置。
  3. 在常规标签页下，前往您的应用部分。
  4. 选择特定的 iOS 或 Android 应用。
  5. 复制应用 ID 值。

设置请求格式

Google Analytics Measurement Protocol 仅支持 HTTP POST 请求。

如要发送事件，请使用以下格式：

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

您必须在请求网址查询参数中提供以下内容（如需详细了解如何查找或创建这些值，请参阅前提条件）：

  • api_secret：用于对请求进行身份验证的 API Secret。
  • firebase_app_id：应用的 Firebase 应用 ID。

您必须以 JSON POST 正文格式为 Measurement Protocol 提供请求正文。示例如下：

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

您必须在请求正文中提供 app_instance_id，以标识移动应用的唯一安装。请注意，这与标识应用本身的 firebase_app_id 不同。如需详细了解 app_instance_id 以及如何使用 Firebase SDK 检索该值，请参阅 app_instance_id 参考文档。

虽然 session_start 是预留的事件名称，但创建新的 session_id 将会创建一个新会话，而无需发送 session_start。了解会话的统计方式。

试用一下

以下示例展示了如何一次发送多个事件。此示例将 tutorial_begin 事件和 join_group 事件发送到您的 Google Analytics 服务器，使用 user_location 字段包含地理位置信息，并使用 device 字段包含设备信息。

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

firebase_app_id 的格式因平台而异。请参阅 Firebase 配置文件和对象下的 应用 ID。

替换时间戳

对于请求中的每个事件和用户属性，Measurement Protocol 会使用在以下列表中找到的第一个时间戳：

  1. 相应事件或用户属性的timestamp_micros。
  2. 请求的 timestamp_micros。
  3. Measurement Protocol 收到请求的时间。

以下示例发送了一个请求级时间戳，该时间戳适用于请求中的所有事件和用户属性。因此，Measurement Protocol 会为 tutorial_begin 和 join_group 事件以及 customer_tier 用户属性分配 requestUnixEpochTimeInMicros 的时间戳。

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

以下示例发送了请求级时间戳、事件级时间戳和用户属性级时间戳。因此，Measurement Protocol 会分配以下时间戳：

  • tutorialBeginUnixEpochTimeInMicros，参加tutorial_begin活动
  • customerTierUnixEpochTimeInMicros 针对 customer_tier 用户属性
  • requestUnixEpochTimeInMicros join_group 事件和 newsletter_reader 用户属性。
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

过去事件和用户属性的验证行为

事件和用户属性的日期最多可以回溯 72 小时。如果 timestamp_micros 值早于 72 小时前，Measurement Protocol 会按如下方式接受或拒绝相应事件或用户属性：

  • 如果 validation_behavior 未设置或设置为 RELAXED，Measurement Protocol 会接受相应事件或用户属性，但会将其时间戳替换为 72 小时前。
  • 如果 validation_behavior 设置为 ENFORCE_RECOMMENDATIONS，Measurement Protocol 会拒绝相应事件或用户属性。

使用 Measurement Protocol 发送的事件（旨在与 Google Analytics for Firebase SDK 或 gtag.js 收集的事件联接或一并处理）应在原始客户端事件时间戳的 48 小时内被 Google Analytics 接收。如果收到的事件晚于此时间，则可能无法按预期处理，尤其是在转化归因等用途方面。

限制

向 Google Analytics 发送 Measurement Protocol 事件时，存在以下限制：

  • 对于每个媒体资源，您每小时最多可以发送 1 亿个非转化请求。如果请求中的所有事件都不是在 Google Ads 中被视为转化的关键事件，则该请求为非转化请求。如果超出此限额，Measurement Protocol 会在当小时剩余时间内默默忽略相应媒体资源的所有非转化请求。

  • 请求最多可以包含 25 个事件。

  • 事件最多可以包含 25 个参数。

  • 事件最多可以包含 25 个用户属性。

  • 用户属性名称不得超过 24 个字符。

  • 用户属性值不得超过 36 个字符。

  • 事件名称不得超过 40 个字符，只能包含字母数字字符和下划线，并且必须以字母字符开头。

  • 参数名称（包括项参数）不得超过 40 个字符，只能包含字母数字字符和下划线，并且必须以字母字符开头。

  • 对于标准 Google Analytics 媒体资源，参数值（包括商品参数值）不得超过 100 个字符；对于 Google Analytics 360 媒体资源，参数值（包括商品参数值）不得超过 500 个字符。

    如果 session_id 和 session_number 参数的值由 Google 跟踪代码管理器中相应的 Analytics 会话 ID 和 Analytics 会话编号 内置变量提供，则此限制不适用。

  • 项参数中最多可以包含 10 个自定义参数。

  • POST 正文必须小于 130kB。

  • 发送到 Google Analytics 的应用 Measurement Protocol 事件不会在 Google Ads 中为应用用户填充搜索广告受众群体。

  • 部分事件、参数和用户属性名称已预留，不能使用。如需了解详情，请参阅预留名称。

预留名称

Measurement Protocol 有多个预留名称，不能用于事件、参数或用户属性。

以下事件名称容易混淆：

如需了解每个使用场景的其他要求，请参阅常见使用场景。