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 替换为请求的载荷。

收到 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 或事件时间戳替换。事件回溯期最长为 3 个日历日（以媒体资源的时区为准）。

user_properties

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

user_data

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

non_personalized_ads

 boolean 可选。设置为 true 以指明不应使用用户的数据来向用户展示个性化广告。

user_location

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

ip_override

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

events[]

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

events[].name

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

events[].params

 object 可选。事件的参数。如需查看系统为各个事件推荐的参数，请参阅事件参考。

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 可选。城市名称。

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 都会将媒体资源的精细位置数据设置应用于相应请求。

自定义参数

您可以在 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

预留的参数名称

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

  • 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_