此页面由 Cloud Translation API 翻译。

迁移到用户代理客户端提示

将网站从依赖于用户代理字符串迁移到新的用户代理客户端提示。

Rowan Merewood

用户代理字符串是大量的被动数字“指纹”收集呈现方式而且难以处理然而，还有各种有效的收集和处理用户代理数据的原因，因此我们需要找到更好的解决方案。用户代理客户端提示同时提供了两种明确的方法来声明您需要用户代理数据和方法，以便在易于使用的格式。

本文将逐步介绍如何审核您对用户代理数据的访问权限，以及将用户代理字符串的使用迁移到用户代理客户端提示。

审核用户代理数据的收集和使用

与任何形式的数据收集一样，您应始终清楚自己为何正在收集信息无论您是否就是了解您在何处以及为什么使用用户代理数据。

如果您不知道是否或在何处使用用户代理数据，请考虑在使用 navigator.userAgent 的前端代码，以及用于使用 User-Agent HTTP 标头。您还应检查前端代码使用已弃用的功能，例如 navigator.platform 和 navigator.appVersion。

从功能的角度来看，需要考虑你在代码中的任何位置录制或处理内容：

浏览器名称或版本
操作系统名称或版本
设备品牌或型号
CPU 类型、架构或位数（例如 64 位）

您也很可能在使用第三方库或服务处理用户代理。在这种情况下，请检查它们是否更新为支持用户代理客户端提示。

是否只使用基本的用户代理数据？

默认的用户代理客户端提示集包括：

Sec-CH-UA：浏览器名称和主要/重要版本
Sec-CH-UA-Mobile：表示移动设备的布尔值
Sec-CH-UA-Platform：操作系统名称 <ph type="x-smartling-placeholder">
- 请注意，规范中对此进行了更新，并将在 Chrome 以及其他基于 Chromium 的浏览器。

建议的用户代理字符串的简化版本也将保留以向后兼容的方式处理这些基本信息例如，将 Chrome/90.0.4430.85，则字符串将包含 Chrome/90.0.0.0。

如果您只检查浏览器名称、主要版本那么您的代码将继续有效，虽然您可能以查看弃用警告。

虽然您可以也应该迁移到用户代理客户端提示，但您的旧版 API 代码或资源限制阻止它。模型中以这种向后兼容的方式输入用户代理字符串虽然现有代码收到的信息不太详细，基本功能

策略：按需客户端 JavaScript API

如果您目前使用的是navigator.userAgent，则应改用首选 navigator.userAgentData，然后再回退以解析用户代理字符串。

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

如果您要检查是移动设备还是桌面设备，请使用布尔值 mobile：

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands 是包含 brand 和 version 的对象数组属性，让浏览器能列出与这些属性的兼容性品牌。您可以直接以数组的形式访问这些数据，也可以使用 some() 调用来检查特定条目是否存在：

function isCompatible(item) {
  // In real life you most likely have more complex rules here
  return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
  // browser reports as compatible
}

userAgentData.brands 包含以不同顺序显示的不同值，因此请勿依赖特定索引中显示的内容。

如果您需要一个更详细的高熵用户代理值，您需要指定该属性并在返回的 Promise 中检查结果：

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

如果您希望从从服务器端处理到客户端处理JavaScript API 不需要访问 HTTP 请求标头，因此可在以下位置请求用户代理值：

策略：静态服务器端标头

如果您在服务器上使用 User-Agent 请求标头，并且需要在您的整个网站中比较一致的数据，这样您就可以在响应中将所需的客户端提示指定为静态集合。这是一个一种比较简单的方法，因为您通常只需在一个位置。例如，如果您已在此处添加标头、您的托管配置或为自己的网站使用哪些框架或平台

如果你要转换或自定义回答内容，可以考虑采用此策略根据用户代理数据提供。

浏览器或其他客户端可能会选择提供不同的默认提示，最好指定所需的全部信息，即使这些信息通常由默认值。

例如，Chrome 的当前默认设置表示为：

🇨?️ 响应标头

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

如果您还希望在响应中接收设备模型，那么发送：

🇨?️ 响应标头

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

在服务器端进行处理时，您应该首先检查 Sec-CH-UA 标头已发送，然后回退到 User-Agent 标头如果不可用，则对其进行解析。

策略：将提示委托给跨源请求

如果您要请求的跨域或跨网站子资源要求用户代理客户端提示需要随其请求发送，您需要使用权限政策明确指定所需的提示。

例如，假设 https://blog.site 在 Google Cloud 上托管资源， https://cdn.site，可返回针对特定设备优化的资源。 https://blog.site可以请求 Sec-CH-UA-Model 提示，但需要使用 Permissions-Policy 将其明确委托给 https://cdn.site。标头。Clients Hints（客户端提示）中提供了政策控制提示的列表。基础设施草稿

🇦?️ 在将提示委托给blog.site时做出的响应

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⬆️ 请求对 cdn.site 上的子资源包含委托提示

Sec-CH-UA-Model: "Pixel 5"

您可以为多个源指定多个提示，而不仅仅是从 ch-ua 范围指定：

🇨?️ 来自 blog.site 将多个提示委托给多个来源的响应

Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
                    ch-dpr=(self "https://cdn.site" "https://img.site")

您无需在 Accept-CH 中包含每个委托提示，但需要为每个提示包含 self，即使您不是直接在顶层使用它也是如此。

策略：将提示委托给 iframe

跨源 iframe 与跨源资源的工作方式类似，在 allow 属性中指定要委托的提示。

🇨?️ 来自blog.site的回复

Accept-CH: Sec-CH-UA-Model

↪️ blog.site 的 HTML

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ 向widget.site提出请求

Sec-CH-UA-Model: "Pixel 5"

iframe 中的 allow 属性会替换符合以下条件的所有 Accept-CH 标头： widget.site 可能会自行发送，因此请确保您已指定 iframe 的网站所必不可少。

策略：动态服务器端提示

如果用户体验历程中有特定部分，您需要有更多选择提示，您可以选择请求这些提示。而不是以静态方式在整个网站上投放这比但是如果您已经为每个路由设置了不同的标头可行。

这里需要注意的一点是，Accept-CH 的每个实例标头将有效地覆盖现有的该组。因此，如果您动态地设置标头，那么每个页面都必须请求所需的全部提示。

例如，您可能希望在网站上有一个版块与用户操作系统保持一致的图标和控件。为此，您可以此外，还想提取 Sec-CH-UA-Platform-Version 来传送适当的子资源。

🇨?️ /blog 的响应标头

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

🇨?️ /app 的响应标头

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

策略：首次请求时需要提供服务器端提示

在某些情况下，您需要的但这种情况很少见回顾了原因。

第一个请求实际上表示针对该源的第一个顶级请求发送的信息。默认提示集包含浏览器其中包含主要版本、平台和移动设备指示器所以问题需要问的问题是，页面首次加载时是否需要扩展数据？

有关第一个请求的其他提示，有两个选项。首先，您可以请使用 Critical-CH 标头。其格式与 Accept-CH 相同而是告知浏览器，如果第一个请求有却没有提供关键提示

⬆️ 初始请求

[With default headers]

🇨?️ 响应标头

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃? 浏览器使用额外标头重试初始请求

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

这会产生第一个请求的重试开销，但是实施成本相对较低。发送额外的标头和浏览器将完成其余工作。

任何 Critical-CH 值都必须是 Accept-CH 中值的子集。Accept-CH 是您希望为网页提供的所有值，Critical-CH 是这些值的子集，您必须具有这些值，否则您无法正确加载网页。

对于需要更多提示的情况首次网页加载时，Client Hints Reliability 提案布置一条路线，以在连接级设置中指定提示。这个使用应用程序层协议对 TLS 的 Settings(ALPS) 扩展 1.3 以在 HTTP/2 和 HTTP/3 连接上实现提示提前传递。这个目前仍处于早期阶段，但如果您积极管理自己的 TLS 和连接设置，那么这正是贡献内容的理想时机。

策略：旧版支持

您的网站上可能存在旧版或第三方代码，具体取决于 navigator.userAgent，包括用户代理字符串中将被触发。从长远来看，您应计划改用等效项 navigator.userAgentData 调用，但有临时解决方案。

UA-CH retrofill 是这个库可让您使用新字符串覆盖 navigator.userAgent，根据请求的 navigator.userAgentData 值构建而成。

例如，此代码会生成一个用户代理字符串，包含“model”提示：

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

生成的字符串将显示 Pixel 5 模型，但仍显示缩减版 92.0.0.0，因为未请求 uaFullVersion 提示：

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

迁移到用户代理客户端提示

审核用户代理数据的收集和使用

是否只使用基本的用户代理数据？

策略：按需客户端 JavaScript API

策略：静态服务器端标头

策略：将提示委托给跨源请求

策略：将提示委托给 iframe

策略：动态服务器端提示

策略：首次请求时需要提供服务器端提示

策略：旧版支持

更多支持