Measurement Protocol 参考

概览

使用 Measurement Protocol 向 Google Analytics 发送数据涉及以下两个方面：

  1. 传输 - 您要向哪里发送数据，以及如何发送数据
  2. 载荷 - 您要发送的数据

本文档介绍了如何设置传输和载荷的格式。

传输

网址端点

若要使用 Measurement Protocol 发送数据，您需要向以下端点发出 HTTP POST 请求：

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

如需发送事件，请发出以下 POST 请求：

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

  • 请求的 BODY。请参阅载荷。

响应代码

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

载荷

通过 Measurement Protocol 发送到 Google Analytics 的数据分为以下两部分：

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

查询参数

参数名称 说明

api_secret

必需。通过 Google Analytics 界面生成的 API Secret。

如需创建新的密钥，请在 Google Analytics 界面中依次转到：
管理 > 数据流 > 选择您的数据流 > Measurement Protocol > 创建

建议仅在您的组织内公开此参数。如果您在客户端部署 Measurement Protocol，则应定期轮替 api_secret，以免产生过多垃圾内容。

firebase_app_id

 必需。Firebase 应用 ID。Firebase 应用的标识符，可在 Firebase 控制台中的以下位置下找到：
项目设置 > 常规 > 您的应用 > 应用 ID

JSON POST 正文

键 类型 说明

app_instance_id

 string

必需。用于对 Firebase 应用的具体安装进行唯一标识。此值需要通过 Firebase SDK 进行检索。

user_id

 string

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

timestamp_micros

 number

可选。与事件相关联的时间的 UNIX 时间戳（以微秒为单位）。此值应仅设置为记录过去发生的事件。此值可通过 user_property 或事件时间戳予以替换。事件回溯期最长为 3 个日历日（以媒体资源的时区为准）。

user_properties

 object 可选。用于衡量的用户属性。如需了解详情，请参阅用户属性。

user_data

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

non_personalized_ads

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

events[]

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

events[].name

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

events[].params

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

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

键 类型 说明

ad_user_data

 string

可选。设置有关出于广告目的向 Google 发送请求事件和用户属性中的用户数据的用户意见征求机制。

必须是 GRANTED 或 DENIED。

ad_personalization

 string

可选。为用户设置有关个性化广告的用户意见征求机制。

必须是 GRANTED 或 DENIED。

自定义参数

除这些指定参数外，您还可以在 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_