用户代理定位

User-Agent 标头历来包含在出价请求中，以提供实用的定位数据，例如发起设备的浏览器和平台。不过，由于 User-Agent 的使用难度较高，并且为了更好地保护用户隐私，浏览器通常会对其进行大量隐去处理。为此，Google 支持 User-Agent Client Hints，并在有可用信息时将其添加到出价请求中，以补充 User-Agent 标头。这些客户端提示（简称“客户端提示”）可以从 Sec-Ch-UA* 标头或 Javascript Client Hints API 获取。

User-Agent 标头会以字符串的形式显示在 BidRequest.device.ua 字段中。

UserAgent 消息将使用可用的 Client Hints 进行填充，但在没有可用 Client Hints 的情况下，则会根据从 User-Agent 标头解析的值进行填充。这会在 BidRequest.device.sua 字段中公开。

强烈建议出价方使用 UserAgent 消息，而不是 User-Agent 字符串。

如何填充 UserAgent

与 User-Agent 标头不同，UserAgent 消息表示用户代理信息，该信息会拆分为多个字段以提供具体信息。

根据广告请求中是否有客户端提示，UserAgent 消息可以通过以下方式填充：

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

示例：根据 User-Agent 标头填充 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

如果包含至少低熵 Client Hints，系统会根据这些标头的内容填充 UserAgent，即使存在 User-Agent 标头也是如此。该代码如下所示：

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

根据 User-Agent 标头填充与根据客户端提示填充

某些字段的填充方式会有所不同，具体取决于它们是基于 User-Agent 标头还是客户端提示。下面简要说明了这些差异：

  • 对于相同的浏览器和平台，UserAgent.browsers.brand 和 UserAgent.platform.brand 通常会因基于 User-Agent 标头或客户端提示的 UserAgent 而异。例如，如果 UserAgent.platform.brand 基于 User-Agent 标头，则可能会显示为“Windows NT”；如果基于 Client Hints，则可能会显示为“Windows”。
  • 某些 UserAgent.browsers 条目是 User-Agent 标头或 Client Hints 所特有的。例如，如果 UserAgent 基于 User-Agent 标头，则会显示“AppleWebKit”；如果基于客户端提示，则只会显示“Chromium”。
  • 只有基于 User-Agent 标头的 UserAgent 可以包含冻结的值。例如，如果平台是 Windows 11 22H2，则 UserAgent.platform.brand 会设置为“Windows NT”，UserAgent.platform.version 会设置为 [“10”, “0”]，因为这是任何 10 或更高版本的 Windows 的冻结值。

UserAgent 中基于客户端提示的数据通常不会不准确地替代冻结或隐去的信息。如果 User-Agent 标头与基于 Client Hints 的 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 条目。这可能与 User-Agent 标头和客户端提示不兼容，因此定位到某些平台可能需要测试两个名称。例如，Apple 的 Macintosh 操作系统在 User-Agent 标头中被标记为“Macintosh”，但在客户端提示中被标记为“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：客户端提示可用，其中至少有一个字段被归类为高熵。