用户代理定位

一直以来，出价请求中包含用户代理标头，以提供有用的定位数据（例如发起设备的浏览器和平台）。不过，由于用户代理难以使用并更好地保护用户隐私，浏览器通常会大量隐去用户代理。为了应对这种情况，Google 支持用户代理客户端提示，当可用时，这些提示包含在出价请求中，用于补充用户代理标头。这些客户端提示（简称）可以来自 Sec-Ch-UA* 标头或 JavaScript Client Hints API。

根据所使用的协议，用户代理标头会通过以下字符串字段之一公开：

  • OpenRTB：BidRequest.device.ua
  • Google RTB（已弃用）：BidRequest.user_agent

UserAgent 消息将在客户端提示可用时使用客户端提示进行填充，否则将根据从用户代理标头中解析的值进行填充。根据使用的协议，此字段将显示为以下字段之一：

  • OpenRTB：BidRequest.device.sua
  • Google RTB（已弃用）：BidRequest.user_agent_data

强烈建议出价方使用 UserAgent 消息，而不要使用用户代理字符串。

UserAgent 的填充方式

与用户代理标头不同，UserAgent 消息表示细分为多个字段以提供特定信息的用户代理信息。

UserAgent 消息可以通过以下方式填充，具体取决于广告请求中是否提供客户端提示：

  • 如果请求至少包含低熵客户端提示，则系统会根据其内容填充 UserAgent。
  • 如果请求仅包含 User-Agent 标头，系统将根据可从标头中解析的内容来填充 UserAgent。

示例：根据用户代理标头填充 UserAgent

假设有一项广告请求，浏览器会发送以下标头：

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36

仅基于 User-Agent 标头填充的 UserAgent 可能如下所示：

browsers: [{ brand: "Mozilla", version: ["5", "0"] },
           { brand: "AppleWebKit", version: ["537", "36"] },
           { brand: "Chrome", version: ["103", "0", "0", "0"] },
           { brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING

示例：根据客户端提示填充 UserAgent

假设有一项广告请求，浏览器会发送以下标头：

User-Agent:                 Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua:                  ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch:             x86
Sec-Ch-Ua-Full-Version:     103.0.5060.134
Sec-Ch-Ua-Mobile:           ?0
Sec-Ch-Ua-Platform:         Windows
Sec-Ch-Ua-Platform-Version: 15.0.0

如果至少包含了低熵客户端提示，那么即使存在用户代理标头，系统也会根据这些标头的内容填充 UserAgent。如下所示：

browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
           { brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
           { brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY

根据用户代理标头填充与根据客户端提示进行填充

某些字段的填充方式有所不同，具体取决于它们是基于用户代理标头还是客户端提示。下面对这些差异进行了总结：

  • 对于相同的浏览器和平台，UserAgent.browsers.brand 和 UserAgent.platform.brand 通常在 UserAgent 之间有所不同，具体取决于用户代理标头或客户端提示。例如，如果 UserAgent.platform.brand 基于 User-Agent 标头，则可能显示为“Windows NT”；如果基于 Client Hints，可能显示为“Windows”。
  • 某些 UserAgent.browsers 条目对于用户代理标头或客户端提示而言是唯一的。例如，如果 UserAgent 基于 User-Agent 标头，系统会显示“AppleWebKit”，而“Chromium”则仅在基于客户端提示时显示。
  • 只有基于 User-Agent 标头的 UserAgent 可以包含冻结值。例如，如果平台是 Windows 11 22H2，则 UserAgent.platform.brand 会设置为“Windows NT”，UserAgent.platform.version 会设置为 [“10”, “0”]，因为对于任何高于 10 的 Windows 版本而言，该值都是冻结值。

UserAgent 中基于客户端提示的数据通常不会不准确地替换已冻结或隐去的信息。如果用户代理标头与基于客户端提示的 UserAgent 不一致，应首选来自 UserAgent 的信息。

UserAgent 对象字段

本部分对各个字段进行了总结，并重点介绍了 Google RTB 所特有的行为和使用最佳做法。

浏览器

包含通常按特异性排序的 BrandVersion 条目列表 - 例如，如果您要列出 browsers 的内容，则每个条目的 brand 可能按以下顺序显示：

品牌 含义
Mozilla 与 Mozilla 兼容
AppleWebKit 基于 AppleWebKit（Mozilla 的一部分）。
Chrome Chrome 浏览器、一部分与 AppleWebKit 兼容的浏览器
Safari 桌面设备变体，而非移动设备。

UserAgent 并不总是按任何特定顺序列出浏览器，尤其是基于客户端提示时。下面说明了根据 source 的值可能会出现的其他差异：

  • USER_AGENT：version 字段可能会缩减为主要版本或被冻结（具体取决于代理专用政策）。请注意，系统不会显示该值已被冻结。
  • CLIENT_HINTS_LOW_ENTROPY 和 CLIENT_HINTS_HIGH_ENTROPY：条目不按任何条件排序；例如，同一浏览器可能在每个请求中以不同顺序发送这些条目。它们可能还包含应忽略的 GREASE 条目。
  • CLIENT_HINTS_HIGH_ENTROPY：浏览器中的所有 version 字段均可设为完整版本。

平台

描述平台的 BrandVersion 条目。这在用户代理标头和客户端提示之间可能不兼容，因此以某些平台为目标可能需要测试两个名称。例如，Apple 的 Macintosh 操作系统在 User-Agent 标头中标注为“Macintosh”，但在 Client Hints 中标注为“macOS”。 下面说明了根据 source 的值可能会出现的其他差异：

  • USER_AGENT：version 字段可能会缩减为主要版本或被冻结。请注意，系统不会显示该值已被冻结。
  • CLIENT_HINTS_LOW_ENTROPY：version 字段不会填充。
  • CLIENT_HINTS_HIGH_ENTROPY：version 字段可设置为完整版本。

移动设备

指明是否应针对小屏幕和/或触控输入优化广告等内容。请注意，这不一定表示设备类型，因为移动浏览器可以配置为请求“桌面版网站”。

架构

标识平台的架构，如“x86”或“arm”。

请注意，对于基于客户端提示的 UserAgent，仅当 source 设置为 CLIENT_HINTS_HIGH_ENTROPY 时，系统才会填充此字段。

位数

标识平台的位数，例如是配备了 32 位还是 64 位 CPU。该字段是一个整数字符串，可提供有关其架构的其他信息；例如，“x86”架构的位数可以设置为“32”或“64”。

请注意，对于基于客户端提示的 UserAgent，仅当 source 设置为 CLIENT_HINTS_HIGH_ENTROPY 时，系统才会填充此字段。

模型

标识设备型号。对于移动设备（不是笔记本电脑或桌面设备），此字段将填充型号名称，例如“Pixel 6 Pro”。

下面说明了根据 source 的值可能会出现的差异：

  • USER_AGENT
    • 非移动设备：model 字段通常包含组合架构和位数值，例如 Windows 的“x64”。此值并非跨平台；例如，Linux 可能针对相同的硬件使用“x86_64”。
    • 移动设备：此字段将不包含架构和位数。 如果您对这些值感兴趣，请参阅 UserAgent.architecture 和 UserAgent.bitness。
  • CLIENT_HINTS_LOW_ENTROPY：model 字段不会填充。
  • CLIENT_HINTS_HIGH_ENTROPY：系统只会为移动设备的设备型号填充 model 字段。没有针对桌面平台设置任何值。

来源

标识用于创建 UserAgent 的标头。对于客户端提示，这还区分了以下两种情况：

  • CLIENT_HINTS_LOW_ENTROPY：只提供基本的客户端提示。
  • CLIENT_HINTS_HIGH_ENTROPY：有客户端提示，其中至少一个字段被归类为高熵。