Measurement Protocol 参考

本文档将介绍如何使用 Measurement Protocol 来向 Google Analytics(分析)发送数据。

概览

使用 Measurement Protocol 向 Google Analytics(分析)发送数据主要有 2 个相关因素:

  • 传输 – 您要向哪里发送数据,以及如何发送数据。
  • 净荷 – 您要发送的数据。

本文档将分别介绍两者的格式。

传输

网址端点

要使用 Measurement Protocol 发送数据,您需要向以下端点发送 HTTP 请求:

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

所有数据都应当使用 HTTPS 协议进行安全发送。

您可以使用 POST 或 GET 请求发送数据。

使用 POST

我们建议您通过 POST 发送数据,因为这种方法可以支持较大的净荷。使用 POST 时,请发送以下 HTTP 请求:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

其中:

  • user_agent_string – 这是一个格式化的用户代理字符串,用于计算以下维度:浏览器、平台及移动功能。

    如果未设置此值,则不会计算以上数据。

  • payload_data – POST 请求的 BODY。主体部分必须仅包含 1 个 URI 编码的负载,长度不能超过 8192 字节。
  • IP 地址 – 在 HTTP 请求中隐含发送的值,用于在 Google Analytics(分析)中计算所有地理位置/网络维度。

GET

在无法发送 POST 数据的环境下,您也可以向同一个端点发送 HTTP GET 请求:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

其中,负载数据将作为 URI 转义的查询参数发送。整个经过编码的网址的长度不能超过 8000 字节。

缓存无效化

在某些环境(例如浏览器)中,HTTP GET 请求可能会被缓存。当请求被缓存时,后续请求就可能会从缓存中检索,而不会发送到 Google Analytics(分析)。为使缓存无效化,Measurement Protocol 提供了一个特殊参数 (z),它可以设置为一个随机数字。这可确保所有 Measurement Protocol 请求都独一无二,因此后续请求不会从缓存中检索。

使用缓存无效化参数时,我们建议您将此参数添加为负载的最后一个参数。

https://www.google-analytics.com/collect?payload_data&z=123456

响应代码

收到 HTTP 请求时,Measurement Protocol 会返回一个 2xx 状态代码。如果净荷数据格式有误,或净荷中的数据不正确,或 Google Analytics(分析)未处理相应数据,Measurement Protocol 不会返回任何错误代码。

如果未收到 2xx 状态代码,您应重试请求,而是应停止发送请求并修正您的 HTTP 请求中的错误。

净荷数据

Google Analytics(分析)使用 Measurement Protocol 收集的所有数据都以净荷的形式发送。净荷的格式与网址查询字符串类似,其中每个参数都有键和值,两者由 = 字符分隔,每个键值对之间使用 & 符号分隔。例如:

key1=val1&key2=val2

每个负载都需要遵守以下方面的规则:必需的值、URI 编码、可一起发送的参数,以及参数长度。每个参数还有一个具体的类型,这会决定了参数值的具体格式。我们将在下文中对这些规则进行说明。

请参阅参数参考,了解您可以使用 Measurement Protocol 发送的所有参数的完整列表。

所有匹配都必需的值

每个净荷都必须包含以下参数:

名称 参数 示例 说明
协议版本 v v=1 协议的版本。值应当为 1
跟踪 ID tid tid=UA-123456-1 该 ID 用于区分是要向哪个 Google Analytics(分析)媒体资源发送数据。
客户 ID cid cid=xxxxx 每位用户专属的ID。
匹配类型 t t=pageview 针对特定用户收集的互动数据类型。

客户端 ID匹配类型数据是直接映射到 Google Analytics(分析)数据模型的值。如果您想要跟踪用户 5555,这位用户浏览了 /pageA/pageB/pageC,您就需要发送如下所示的 3 个负载:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

请注意,/ 被编码为 %2F

网址编码值

所有发送到 Google Analytics(分析)的值都必须采用 UTF-8 编码并经过网址编码。要发送键 dp 及其值 /my page €,您首先需要确保此值采用的编码为 UTF-8 并且经过了网址编码,最终的字符串应如下所示:

dp=%2Fmy%20page%20%E2%82%AC

如果有任何字符的编码不正确,它们将会被 Unicode 替换字符 xFFFD所替换。

特定匹配类型的必需值

某些参数只能随特定的匹配类型发送。例如,pageview 匹配类型还要求设置网页路径 (dp) 参数。参数参考中介绍了各匹配类型必需的参数。

长度上限

Measurement Protocol 中的某些文本值有长度上限(以字节为单位)。例如,文档引荐来源网址 dr 字段的长度上限为 2048 字节。如果有任何值的长度超过了上限,它们将自动被截短。如果是一个多字节字符超过了长度上限,则整个字符都会被截掉。

支持的数据类型

Measurement Protocol 中的每个数据字段都属于某一类型,每个类型都有自己的数据验证规则。如果任何参数值不符合验证规则,则该参数将被忽略,Google Analytics(分析)将不会对其进行处理。所有其他参数将会照常进行到处理。

Measurement Protocol 支持以下数据类型:

请注意,每个数据字段都有自己的限制。请参阅字段参考,了解所有数据字段及其接受的类型的完整列表。

文本

用于表示字符串。文本字段会进行额外处理。开头和末尾的所有空白字符都会被移除。字符串中间连续的两个或更多空白字符(包括空格、制表符、换行符等)会被缩减为一个空格字符。这一转换操作会在截短操作之前在原始文本的基础上进行。例如:

   Hello      World

将变为:

Hello World

货币

用于表示货币总价值。小数点用于分隔货币值的整数部分和小数部分。值最多可精确到小数点后 6 位。以下值是有效的货币字段:

1000.000001

货币值发送到 Google Analytics(分析)后,首位数字、字符 - 号或 .(小数点)之前的所有文字都将被移除。都将被移除。因此:

$-55.00

将变为:

-55.00

布尔值

用于决定某个值是 true 还是 false。有效值包括:

  • 1 – True
  • 0 – False

整数

用于表示整数。此类值会被存储为 64 位有符号整数数据类型

数字

用于表示整数或浮点数。