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

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

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

设置请求格式

Google Analytics（分析）Measurement Protocol 仅支持 HTTP POST 请求。

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

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

必须在请求网址中提供以下内容：

api_secret：Google Analytics 界面中生成的 API 密钥 。

如需创建新的密钥，请依次转到：管理 > 数据收集和修改 > 数据流 > 选择您的数据流 > Measurement Protocol API 密钥 > 创建。

firebase_app_id：Firebase 应用 ID，可在 Firebase 控制台的以下位置下找到：项目设置 > 常规 > 您的应用 > 应用 ID 。

firebase_app_id 不同于 app_instance_id。firebase_app_id 用于标识您的应用，而 app_instance_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
        }
      }
   ]
  }

虽然 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 的格式因平台而异。请参阅 应用 ID 下的 Firebase 配置文件和对象。

替换时间戳

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

事件或用户属性的 timestamp_micros。
请求的 timestamp_micros。
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 会分配以下时间戳：

tutorial_begin 事件的 tutorialBeginUnixEpochTimeInMicros
customer_tier 用户属性的 customerTierUnixEpochTimeInMicros
join_group 事件和 newsletter_reader 用户属性的 requestUnixEpochTimeInMicros。

{
  "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 事件时，存在以下限制：

请求最多可以包含 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 中为应用用户填充搜索广告受众群体。

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