使用者代理客戶端提示 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