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,以免产生过多垃圾内容。

JSON POST 正文

类型 说明

user_id

string

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

timestamp_micros

number

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

user_properties

object 可选。用于衡量的用户属性。如需了解详情,请参阅用户属性
object 可选。指定请求的用户意见征求设置。如需了解详情,请参阅“Consent”部分

non_personalized_ads

boolean 可选。设置为 true,表明不应让用户的数据 用于投放个性化广告。 <ph type="x-smartling-placeholder">

events[]

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

events[].name

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

events[].params

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

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

类型 说明

ad_user_data

string

可选。设置有关通过请求的 事件和用户属性,用于向 Google 发送数据,以用于广告目的。

必须是 GRANTEDDENIED

ad_personalization

string

可选。设置针对用户投放个性化广告的同意情况。

必须是 GRANTEDDENIED

自定义参数

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