本文档将介绍如何使用 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 |
针对特定用户收集的互动数据类型。 |
Client ID
和 Hit Type
数据是直接映射到 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
– True0
– False
整数
用于表示整数。此类值会被存储为 64 位有符号整数数据类型
数字
用于表示整数或浮点数。