用户代理定位

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

根据所使用的协议，User-Agent 标头会通过以下某个字符串字段公开：

  • Google：BidRequest.user_agent
  • OpenRTB：BidRequest.device.ua

UserAgent 消息将在客户端提示可用时填充，但将根据从 User-Agent 标头中解析的值进行填充。根据所使用的协议，此字段将作为以下某个字段公开：

  • Google：BidRequest.user_agent_data
  • OpenRTB：BidRequest.device.sua

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

UserAgent 的填充方式

与用户代理标头不同，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

如果至少包含低熵客户端提示，即使存在用户代理标头，系统也会根据这些标头的内容填充 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 标头或客户端提示，UserAgent 之间的 UserAgent.browsers.brand 和 UserAgent.platform.brand 往往会有所不同。例如，如果 UserAgent.platform.brand 基于 User-Agent 标头，则显示为“Windows NT”；如果基于 Client Hints，则显示为“Windows”。
  • 某些 UserAgent.browsers 条目是用户代理标头或客户端提示所独有的。例如，如果 UserAgent 基于用户代理标头，就会显示“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 实时出价特有的行为以及使用方面的最佳做法。

浏览器

包含 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”，但在客户端提示中的品牌为“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：可使用客户端提示，包括至少一个被归类为高熵的字段。