用户代理客户端提示 API

概念与用法

在历史上，解析 User-Agent 字符串一直是获取有关用户浏览器或设备信息的途径。典型的 User-Agent 字符串如下面的示例所示，它标识了 Windows 上的 Chrome 92。

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36

User agent Client Hints 旨在通过强制执行一种服务器请求一组信息的模型，以一种更保护隐私的方式提供这些信息。浏览器决定返回什么。这种方法意味着 User-Agent 可以提供允许用户隐藏部分可能用于指纹识别的信息的设置。

为了决定返回什么，通过此 API 访问的信息分为两组——低熵和高熵提示。低熵提示是指不泄露过多信息的提示，API 使这些提示在每次请求时都易于访问。高熵提示有可能泄露更多信息，因此受到限制，浏览器可以据此决定是否提供它们。这个决定可能基于用户偏好，或者需要权限请求。

User-Agent Client Hints 的用例

潜在用例包括

• 当识别出用户浏览器缺少某些 Web 平台功能时，为用户提供量身定制的 polyfill。
• 解决浏览器 bug。
• 记录浏览器分析数据。
• 根据 User-Agent 信息调整内容。这包括为移动设备提供不同的内容，特别是被识别为低功耗的设备。也可能包括调整设计以适应用户操作系统的界面，或提供特定于操作系统的链接。
• 当用户从不同的浏览器或设备登录时，提供通知，作为安全功能。
• 在提供下载的网站上，提供正确的二进制可执行文件。
• 收集有关浏览器和设备的信息以识别应用程序错误。
• 阻止垃圾邮件发送者、机器人和爬虫。

接口

NavigatorUAData

提供属性和方法来访问有关用户浏览器和操作系统的用户数据。

其他接口的扩展

Navigator.userAgentData 只读

返回一个 NavigatorUAData 对象，该对象提供对用户浏览器和操作系统信息的访问。

WorkerNavigator.userAgentData 只读

返回一个 NavigatorUAData 对象，该对象提供对用户浏览器和操作系统信息的访问。

示例

获取品牌信息

下面的示例将 NavigatorUAData.brands 的值打印到控制台。

console.log(navigator.userAgentData.brands);

返回高熵值

在下面的示例中，使用 NavigatorUAData.getHighEntropyValues() 方法请求了多个提示。当 Promise 解析后，这些信息将被打印到控制台。

navigator.userAgentData
  .getHighEntropyValues([
    "architecture",
    "model",
    "platform",
    "platformVersion",
    "fullVersionList",
  ])
  .then((ua) => {
    console.log(ua);
  });

规范

浏览器兼容性

api.NavigatorUAData

api.Navigator.userAgentData

api.WorkerNavigator.userAgentData

另见

• 通过 User-Agent Client Hints 改进用户隐私和开发者体验
• 迁移到 User-Agent Client Hints