用户代理定位

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.brandUserAgent.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_AGENTversion 字段可能会缩减为主要版本或冻结(具体取决于代理专用政策)。请注意,系统不会指明值已冻结。
  • CLIENT_HINTS_LOW_ENTROPYCLIENT_HINTS_HIGH_ENTROPY:条目未按任何标准排序;例如,同一浏览器可能会在每次请求中以不同的顺序发送这些条目。它们可能还包含一个 GREASE 条目,应予忽略。
  • CLIENT_HINTS_HIGH_ENTROPY:浏览器中找到的所有 version 字段都可以设置为完整版本。

平台

用于描述平台的 BrandVersion 条目。这可能与 User-Agent 标头和客户端提示不兼容,因此定位到某些平台可能需要测试两个名称。例如,Apple 的 Macintosh 操作系统在 User-Agent 标头中被标记为“Macintosh”,但在客户端提示中被标记为“macOS”。下面介绍了您可能会根据 source 的值看到的其他差异:

  • USER_AGENTversion 字段可能会缩减为主要版本或冻结。请注意,系统不会指明值已冻结。
  • CLIENT_HINTS_LOW_ENTROPY:系统不会填充 version 字段。
  • CLIENT_HINTS_HIGH_ENTROPYversion 字段可以设置为完整版本。

移动设备

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

架构

用于标识平台的架构,例如“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.architectureUserAgent.bitness
  • CLIENT_HINTS_LOW_ENTROPY:系统不会填充 model 字段。
  • CLIENT_HINTS_HIGH_ENTROPY:系统仅会为移动设备的设备型号填充 model 字段。未为桌面平台设置任何值。

来源

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

  • CLIENT_HINTS_LOW_ENTROPY:仅提供基本客户端提示。
  • CLIENT_HINTS_HIGH_ENTROPY:客户端提示可用,其中至少有一个字段被归类为高熵。