用户代理定位

User-Agent 标头历来都包含在出价请求中，以提供实用的定位数据，例如发起设备的浏览器和平台。不过，由于用户代理字符串难以使用，且为了更好地保护用户隐私，浏览器通常会对其进行大量编辑。为此，Google 支持 User-Agent Client Hints，这些提示会在出价请求中提供（如果可用），以补充 User-Agent 标头。这些客户端提示（简称）可来自 Sec-Ch-UA* 标头或 JavaScript 客户端提示 API。

User-Agent 标头以字符串形式在 BidRequest.device.ua 字段中公开。

UserAgent 消息会在 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

如果包含至少低熵客户端提示，即使存在 User-Agent 标头，系统也会根据这些标头的内容填充 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

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

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

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

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：客户端提示可用，包括至少一个归类为高熵的字段。