This documentation is for Universal Analytics. See Measurement Protocol (Google Analytics 4) if you are using Google Analytics 4.

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 位有符号整数数据类型

数字

用于表示整数或浮点数。