本頁面由 Cloud Translation API 翻譯而成。

遷移至使用者代理程式用戶端提示

以下的策略，有助於將網站從依賴使用者代理程式字串遷移至新的使用者代理程式用戶端提示

Rowan Merewood

使用者代理程式 string 是大量被動式數位指紋採集顯示在瀏覽器中但難以處理不過，為什麼需要收集和處理使用者代理程式資料更好的解決方案「使用者代理程式用戶端提示」提供了明確的方式宣告自己需要使用者代理程式資料和方法，才能在格式簡單好上手

本文將逐步說明如何稽核您的使用者代理程式資料存取權。將使用者代理程式字串使用情形遷移至 User-Agent Client Hints。

稽核使用者代理程式資料的收集和使用方式

不論採用哪種資料收集方式，都應該瞭解您為什麼收集的資料。無論您是否已完成才能瞭解您會使用使用者代理程式資料的位置和原因。

如果您不確定使用者代理程式資料的使用方式或位置，建議您搜尋使用 navigator.userAgent 的前端程式碼以及使用 User-Agent HTTP 標頭此外，您也應該檢查前端程式碼以便使用已不適用的功能，例如 navigator.platform 和 navigator.appVersion。

從功能的角度而言，思考程式碼中的任何位置錄製或處理：

瀏覽器名稱或版本
作業系統名稱或版本
裝置廠牌或型號
CPU 類型、架構或位元程度 (例如 64 位元)

您可能會使用第三方程式庫或服務來處理使用者代理程式在這種情況下，請檢查各版本是否已更新為支援「使用者代理程式用戶端提示」。

您只能使用基本的使用者代理程式資料嗎？

預設的「使用者代理程式用戶端提示」包括：

Sec-CH-UA：瀏覽器名稱和主要/重要版本
Sec-CH-UA-Mobile：代表行動裝置的布林值
Sec-CH-UA-Platform：作業系統名稱
- 請注意，本規格已更新， Chrome 和其他以 Chromium 為基礎的瀏覽器

我們提議的縮減版本，將保留以回溯相容的方式取得這些基本資訊舉例來說 Chrome/90.0.4430.85，此字串將會包含 Chrome/90.0.0.0。

您只需檢查使用者代理程式字串中的瀏覽器名稱、主要版本或作業系統，您的程式碼就會持續運作，儘管您即可查看淘汰警示

雖然您可以且應該遷移到「使用者代理程式用戶端提示」，但您可以使用或資源限制減少以回溯相容的方式寫入使用者代理程式字串現有程式碼雖然會收到較少詳細資訊，但都保留基本功能

策略：隨選用戶端 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
  });

如果您想要從 30 天之後改用到用戶端處理JavaScript API 沒有需要存取 HTTP 要求標頭，因此可在。

策略：靜態伺服器端標頭

如果您在伺服器上使用 User-Agent 要求標頭，且需要在整個網站上在回應中將所需的用戶端提示指定為靜態集合。這是因為通常只需要在一個叢集中設定或 HTTP/HTTPS 位置例如，該位置可能已在網路伺服器設定中新增標頭、代管設定或導入的架構或平台

如果您要轉換或自訂回應，請考慮此策略根據使用者代理程式資料提供服務

瀏覽器或其他用戶端可能會選擇提供不同的預設提示，建議您指定所需的所有項目，即使一般是由 Google 所提供預設值。

舉例來說，目前的 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 會在 https://cdn.site，可傳回針對特定裝置最佳化的資源。「https://blog.site」可以要求提供 Sec-CH-UA-Model 提示，但需要使用 Permissions-Policy 明確將其委派給 https://cdn.site 標題。如要查看政策控制提示清單，請參閱「用戶端提示」基礎設施草稿

⬇️ 來自 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 的每個例項標題將有效覆寫現有組合。如果您是以動態方式設定標頭之後，每個網頁都必須要求完整的必要提示。

例如，您可能希望在網站上提供 1 個部分符合使用者作業系統的圖示和控制項為此，您可以而要另外提取 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 是您「必須」擁有或無法正確載入網頁值的子集。

如果需要真的需要提示載入第一個網頁時，「用戶端提示可靠性」提案設立路徑，以便在連線層級設定中指定提示。這個利用應用程式層通訊協定 (Application-Layer Protocol) Settings (ALPS) 擴充功能至傳輸層安全標準 (TLS) 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

進一步支援

如果這些策略無法滿足您的使用需求，請在 privacy-sandbox-dev-support 存放區讓我們一起探索你的問題。

相片來源：Ricardo Rocha 在 Unsplash 裝置上