Measurement Protocol 参考文档

本页介绍了 Measurement Protocol 的传输机制和数据参数。

传输

所有数据都必须使用 HTTPS POST 请求安全地发送。

向以下端点发送请求：

https://www.google-analytics.com/mp/collect

如果您希望在欧盟境内收集数据，请改用以下端点：

https://region1.google-analytics.com/mp/collect

以下是 POST 请求示例：

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

将 PAYLOAD_DATA 替换为请求的 Payload。

收到 HTTP 请求时，Measurement Protocol 会返回 2xx 状态代码。如果载荷格式有误，或者数据不正确或未被 Google Analytics 处理，Measurement Protocol 不会返回任何错误代码。

载荷

载荷包含两个部分：

  1. 查询参数。
  2. JSON POST 正文。

查询参数

参数名称 说明

api_secret

 必需。Google Analytics 界面中的 API 密钥。

可在以下位置下找到：管理 > 数据流 > 选择您的数据流 > Measurement Protocol > 创建。

仅向组织内部的受邀用户公开。应定期更新，以免产生过多垃圾内容。

JSON POST 正文

键 类型 说明

user_id

 string

可选。用户的唯一标识符。如需详细了解此标识符，请参阅使用 User-ID 进行跨平台分析。 只能包含 UTF-8 字符。

timestamp_micros

 number

可选。Unix 时间戳，以微秒为单位，而非毫秒。表示活动的时间。应仅设置为记录过去发生的事件。可通过 user_property 或事件时间戳予以替换。事件回溯期最长为 72 小时。

user_properties

 object 可选。用于衡量的用户属性。

user_data

 object 可选。用户提供的数据。
object 可选。相应请求的用户意见征求设置。如需了解详情，请参阅“Consent”部分。

non_personalized_ads

 boolean 可选。设置为 true 以指明不应将用户的数据用于个性化广告。

user_location

 object 可选。以结构化格式为请求设置地理位置信息。

ip_override

 string 可选。Google Analytics 用于为请求派生地理位置信息的 IP 地址。

device

 object 可选。以结构化格式为请求设置设备信息。

validation_behavior

 string

可选。为请求设置验证行为。

RELAXED 或 ENFORCE_RECOMMENDATIONS。如果未指定，则默认为 RELAXED。

events[]

 array 必需。一个包含 event 个元素的数组。每个请求最多可以发送 25 个事件。如需查看所有有效事件，请参阅事件参考。

events[].name

 string 必需。活动名称。如需查看所有选项，请参阅事件。

events[].params

 object 可选。相应活动的参数。如需查看系统为各个事件推荐的参数，请参阅事件，另请参阅常见事件参数。

常用事件参数

Measurement Protocol 具有以下常见事件参数：

键 类型 说明

session_id

 number 用于标识用户会话的正数。对于一些常见使用情形，此权限是必需的。 必须与正则表达式 ^\d+$ 匹配。

engagement_time_msec

 number 相应事件的用户互动时长（以毫秒为单位）。使用一个反映自上一个事件以来用户参与时长的值。

timestamp_micros

 number 相应事件的 Unix 纪元时间（以微秒为单位）。使用此参数可替换事件的时间戳。

consent 属性用于配置用户意见征求类型和同意情况。如果您不指定 consent，Google Analytics 会使用相关客户或应用实例的相应线上互动的用户意见征求设置。

键 类型 说明

ad_user_data

 string

可选。有关出于广告目的将请求中的事件和用户属性的用户数据发送给 Google 的用户意见征求情况。

GRANTED 或 DENIED。

ad_personalization

 string

可选。用户对个性化广告的同意情况。

GRANTED 或 DENIED。

地理位置信息

user_location 和 ip_override 属性提供地理位置信息。 user_location 优先于 ip_override。

以下是 user_location 字段的结构。请提供尽可能多的属性。我们建议至少使用 country_id 和 region_id。

键 类型 说明

city

 string 可选。城市名称。如果城市位于美国，请同时设置 country_id 和 region_id，以便 Google Analytics 能够将城市名称正确映射到城市 ID。

region_id

 string 可选。ISO 3166 国家/地区和子区域。例如，US-CA、US-AR、CA-BC、GB-LND、CN-HK。

country_id

 string 可选。国家/地区，采用 ISO 3166-1 alpha-2 格式。例如，US、AU、ES、FR。

subcontinent_id

 string 可选。采用 UN M49 格式的次大陆。例如，011、021、030、039。

continent_id

 string 可选。采用 UN M49 格式表示的大陆。例如，002、019、142、150。

以下是 user_location 的示例：

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override 是 user_location 的替代方案。如果您改为发送 ip_override，Google Analytics 会根据 IP 地址得出地理位置信息。 如果您发送 user_location，Google Analytics 会忽略 ip_override。

如果您不发送 user_location 或 ip_override，Google Analytics 会使用 client_id。

无论发送的地理位置信息如何，Google Analytics 都会将媒体资源的精细地理位置数据设置应用于相应请求。

设备信息

如需发送设备信息，请使用 device 字段。以下是 device 字段的结构。提供尽可能多的属性。我们建议至少使用 category。

键 类型 说明

category

 string 可选。设备的类别。例如： desktop tablet mobile smart TV。

language

 string 可选。语言，采用 ISO 639-1 格式。例如，en、en-US。

screen_resolution

 string 可选。设备的分辨率，格式为 WIDTHxHEIGHT。例如，1280x2856、1080x2340。

operating_system

 string 可选。操作系统或平台。例如 MacOS。

operating_system_version

 string 可选。操作系统或平台的版本。例如，13.5。

model

 string 可选。设备的型号。例如，Pixel 9 Pro、Samsung Galaxy S24。

brand

 string 可选。设备的品牌。例如，Google、Samsung。

browser

 string 可选。浏览器品牌或类型。例如，Chrome、Firefox。

browser_version

 string 可选。浏览器版本。例如，136.0.7103.60、5.0。

以下代码段展示了 device 设置的示例：

"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"
}

无论您指定的是 Google Analytics 都会将相应媒体资源的精细设备数据设置应用于请求。

验证行为

validation_behavior 属性用于控制 Measurement Protocol 如何验证请求的内容。

  • RELAXED 验证仅拒绝格式错误的请求。它可能仍会接受字段名称无效或数据类型不正确的事件和参数，但会忽略超出限制的参数。默认情况下，衡量协议使用 RELAXED 验证。
  • ENFORCE_RECOMMENDATIONS 验证会拒绝类型不正确的事件和商品参数，或包含超出限制的参数的事件和商品参数。此外，ENFORCE_RECOMMENDATIONS 会拒绝任何时间戳不在过去 72 小时内的事件或用户属性。

我们建议您采取以下方法：

  • 在验证事件时使用 ENFORCE_RECOMMENDATIONS，以便尽可能多地获取有关请求潜在问题的反馈。

    您还可以使用事件构建器验证请求，因为该构建器在验证请求时会指定 ENFORCE_RECOMMENDATIONS。

  • 在发送事件时，请勿指定 validation_behavior，以最大限度地减少被 Measurement Protocol 拒绝的数据。

    如果您希望在发送特定请求时优先进行严格验证，而不是收集数据，请添加 validation_behavior 字段并将其设置为 ENFORCE_RECOMMENDATIONS。

自定义参数

您可以在 Measurement Protocol 载荷中加入用户级范围的自定义参数、事件级范围的自定义参数和商品级范围的自定义参数。

  • 用户级范围的自定义参数可包含在 user_properties 中。
  • 事件级范围的自定义参数可包含在 events[].params 中。
  • 商品级范围的自定义参数可包含在 items 中。

某些事件具有推荐参数。如需查看所有受支持的事件的推荐参数，请参阅事件。

预留名称

某些事件名称、参数名称和用户属性名称已预留，无法使用：

预留的事件名称

以下事件名称已预留，不能使用：

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

此外，ad_impression、in_app_purchase 和 screen_view 事件仅允许用于应用数据流。

预留的参数名称

以下参数名称已预留，不能使用：

  • firebase_conversion

参数名称不得以下列内容开头：

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

预留的用户属性名称

以下用户属性名称已预留，不能使用：

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

此外，用户属性名称不能以下列内容开头：

  • _ (underscore)
  • firebase_
  • ga_
  • google_