此页面由 Cloud Translation API 翻译。

向 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 > 创建。

measurement_id：与数据流关联的衡量 ID，可在 Google Analytics 界面的以下位置下找到：管理 > 数据流 > 选择您的数据流 > 衡量 ID。

measurement_id 并不是数据流 ID。

如需获取完整的参考信息，请参阅查询参数。

必须在请求正文中提供以下内容：

client_id：客户端的唯一标识符。该标识符与 Firebase app_instance_id 不同。请使用 gtag.js('get')。

user_id：可选。用户的唯一标识符。只能包含 UTF-8 字符。如需详细了解此标识符，请参阅使用 User-ID 进行跨平台分析。
consent：可选。了解如何设置用户意见征求设置。
timestamp_micros：可选。请求中事件和用户属性的 Unix 纪年时间（以微秒为单位）。如果未指定，则默认为请求时间。
events：一个由多个事件项构成的数组。您可以在一个请求中包含多个事件。

若要在报告（如实时报告）中显示用户活动，必须将 engagement_time_msec 和 session_id 作为 event 的 params 的一部分提供。engagement_time_msec 参数应反映事件的互动时长（以毫秒为单位）。

示例如下：

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

试试看

您可以使用以下示例一次发送多个事件。此示例会将 tutorial_begin 事件和 join_group 事件发送到您的 Google Analytics 服务器。

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "engagement_time_msec": 150
        }
      }
    ]
  })
});

替换时间戳

Measurement Protocol 会针对请求中的每个事件使用它在以下列表中找到的第一个时间戳：

事件的 timestamp_micros。
请求的 timestamp_micros。
Measurement Protocol 收到请求的时间。

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

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

以下示例同时发送请求级时间戳和事件级时间戳。因此，Measurement Protocol 会为 tutorial_begin 事件分配时间戳 tutorialBeginUnixEpochTimeInMicros，并为 join_group 事件分配时间戳 requestUnixEpochTimeInMicros。

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

限制

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

请求最多可以包含 25 个事件。
事件最多可以包含 25 个参数。
事件最多可以包含 25 个用户属性。
用户属性名称不得超过 24 个字符。
用户属性值不得超过 36 个字符。
事件名称不得超过 40 个字符，只能包含字母数字字符和下划线，并且必须以字母字符开头。
参数名称（包括项参数）不得超过 40 个字符，只能包含字母数字字符和下划线，并且必须以字母字符开头。
对于标准版 Google Analytics 媒体资源，参数值（包括商品参数值）不得超过 100 个字符；对于 Google Analytics 360 媒体资源，参数值（包括商品参数值）不得超过 500 个字符。
项参数中最多可以包含 10 个自定义参数。
POST 正文必须小于 130kB。
发送到 Google Analytics 的应用 Measurement Protocol 事件不会在 Google Ads 中为应用用户填充搜索广告受众群体。

如需了解每种用例的其他要求，请参阅常见用例。