指定使用者代理程式

出價要求先前包含使用者代理程式標頭，可提供實用的指定資料，例如啟動的裝置瀏覽器和平台。不過，瀏覽器之所以會大幅遮蓋使用者代理程式，是因為該代理程式在使用上較為困難，並能更妥善地保護使用者隱私。為因應這項異動，Google 支援使用者代理程式用戶端提示，如果可用以補充 User-Agent 標頭，就會包含在出價要求中。這些用戶端提示 (簡稱) 可從 Sec-Ch-UA* 標頭或 JavaScript Client Hints API 取得。

視使用的通訊協定而定，User-Agent 標頭會透過下列其中一個字串欄位公開：

  • Google：BidRequest.user_agent
  • OpenRTB：BidRequest.device.ua

當 UserAgent 訊息可用時，系統會填入 Client Hints，但將根據從使用者代理程式標頭剖析的值填入。視使用的通訊協定而定，這將以下列其中一個欄位的形式公開：

  • Google：BidRequest.user_agent_data
  • OpenRTB：BidRequest.device.sua

強烈建議出價方使用 UserAgent 訊息，而非使用者代理程式字串。

UserAgent 的填入方式

與 User-Agent 標頭不同，UserAgent 訊息代表的使用者代理程式資訊細分為多個欄位，以提供特定資訊。

視廣告請求中是否提供用戶端提示而定，您可以透過以下方式填入 UserAgent 訊息：

  • 如果要求包含至少低熵的用戶端提示，系統會根據其內容填入 UserAgent。
  • 如果要求中只包含 User-Agent 標頭，系統會根據可從標頭剖析的內容填入 UserAgent。

範例：根據使用者代理程式標頭填入 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

如果包含至少低熵用戶端提示，則即使有 User-Agent 標頭，系統也會根據這些標頭的內容填入 UserAgent。如下所示：

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 之間通常會有 UserAgent.browsers.brand 和 UserAgent.platform.brand 差異。舉例來說，如果以 User-Agent 標頭為基礎，UserAgent.platform.brand 可能就會顯示為「Windows NT」；如果採用用戶端提示，則可能會顯示「Windows」。
  • 有些 UserAgent.browsers 項目是使用者代理程式標頭或用戶端提示專用的項目。舉例來說，如果 UserAgent 是以使用者代理程式標頭為依據，就會顯示「AppleWebKit」，而「Chromium」則只有在以用戶端提示為依據時才會顯示。
  • 只有以 User-Agent 標頭為基礎的 UserAgent 可包含凍結值。舉例來說，如果平台是 Windows 11 22H2，UserAgent.platform.brand 會設為「Windows NT」，UserAgent.platform.version 則設為 [“10”, “0”]，因為這是所有搭載 10 以上版本 Windows 版本的凍結值。

以用戶端提示為依據的 UserAgent 資料，通常可能無法取代凍結或遮蓋的資訊。如果 User-Agent 標頭與根據用戶端提示的 UserAgent 之間有任何不一致，則建議您從 UserAgent 取得資訊。

UserAgent 物件欄位

本節將概述各個欄位，並著重於 Google RTB 專屬行為和使用最佳做法。

瀏覽器

包含一般按特定性排序的 BrandVersion 項目清單。舉例來說，假設您要列出 browsers 的內容，則每個項目的 brand 可能會按照下列順序顯示：

品牌 意義
Mozilla 與 Mozilla 相容
AppleWebKit AppleWebKit 式，即 Mozilla 的子集。
Chrome Chrome 瀏覽器 (與 AppleWebKit 相容的部分瀏覽器)
Safari 電腦版和行動版的變化版本。

UserAgent 不一定會以任何特定順序列出瀏覽器，特別是在以用戶端提示為基礎的情況下。以下說明根據 source 的值，可能會出現的其他差異：

  • USER_AGENT：version 欄位可能會縮減為主要版本或凍結 (視代理程式專屬政策而定)。請注意，系統不會表示該值已凍結。
  • CLIENT_HINTS_LOW_ENTROPY 和 CLIENT_HINTS_HIGH_ENTROPY：項目不會按任何條件排序。舉例來說，同一個瀏覽器可能會在每項要求中，以不同的順序傳送這些項目。也可能包含應忽略的 GREASE 項目。
  • CLIENT_HINTS_HIGH_ENTROPY：在瀏覽器中找到的所有 version 欄位都可以設為完整版本。

平台

說明平台的 BrandVersion 項目。這可能無法與使用者代理程式標頭和用戶端提示相容，因此指定某些平台可能需要測試兩個名稱。舉例來說，Apple 的 Macintosh 作業系統在 User-Agent 標頭中是「Macintosh」，但 Client Hints 中是「macOS」。以下說明根據 source 的值，可能會出現的其他差異：

  • USER_AGENT：version 欄位可降為主要版本或凍結。請注意，您沒有指示該值已凍結。
  • CLIENT_HINTS_LOW_ENTROPY：version 欄位不填入值。
  • CLIENT_HINTS_HIGH_ENTROPY：version 欄位可設為完整版本。

行動裝置

指出是否應該針對小螢幕和/或觸控輸入，對廣告等內容進行最佳化。請注意，這不一定是裝置類型的指標，因為行動瀏覽器可以設為要求「電腦版網站」。

架構

識別平台的架構，例如「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.architecture 和 UserAgent.bitness。
  • CLIENT_HINTS_LOW_ENTROPY：model 欄位不填入值。
  • CLIENT_HINTS_HIGH_ENTROPY：只有行動裝置的裝置型號才會填入 model 欄位。尚未針對電腦平台設定任何值。

來源

識別要使用哪些標頭建立 UserAgent。如果是用戶端提示，這麼做也可以區分以下兩種情況：

  • CLIENT_HINTS_LOW_ENTROPY：僅提供基本用戶端提示。
  • CLIENT_HINTS_HIGH_ENTROPY：可使用用戶端提示，包括至少一個分類為高熵的欄位。