指定使用者代理程式

出價要求一向會包含 User-Agent 標頭，提供實用的指定目標資料，例如啟動裝置的瀏覽器和平台。不過，由於使用者代理程式難以使用，且為了進一步保護使用者隱私，瀏覽器通常會大量遮蓋使用者代理程式。為此，Google 支援 User-Agent Client Hints，這項資訊會納入出價要求 (如有)，做為 User-Agent 標頭的補充資訊。這些用戶端提示 (簡稱) 可來自 Sec-Ch-UA* 標頭或 JavaScript 用戶端提示 API。

User-Agent 標頭會以字串形式顯示在 BidRequest.device.ua 欄位中。

如果 Client Hints 可用，系統會以這些資訊填入 UserAgent 訊息，否則會根據從 User-Agent 標頭剖析的值填入。這會顯示在 BidRequest.device.sua 欄位中。

強烈建議出價者使用 UserAgent 訊息，而非 User-Agent 字串。

UserAgent 的填入方式

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

視廣告請求中是否有用戶端提示，UserAgent訊息可透過下列方式填入：

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

示例：根據 User-Agent 標頭填入 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.browsers.brand 和 UserAgent.platform.brand 通常會因 UserAgent 而有所不同，具體取決於 User-Agent 標頭或用戶端提示。舉例來說，如果 UserAgent.platform.brand 是以 User-Agent 標頭為依據，則可能顯示為「Windows NT」；如果以 Client Hints 為依據，則可能顯示為「Windows」。
  • 部分 UserAgent.browsers 項目是 User-Agent 標頭或 Client Hints 專屬的。舉例來說，如果 UserAgent 是根據 User-Agent 標頭，則會顯示「AppleWebKit」，但如果是根據用戶端提示，則只會顯示「Chromium」。
  • 只有根據 User-Agent 標頭的 UserAgent 可以包含凍結值。 舉例來說，如果平台是 Windows 11 22H2，UserAgent.platform.brand 會設為「Windows NT」，UserAgent.platform.version 則會設為 [“10”, “0”]，因為這是 Windows 10 以上任何版本的凍結值。

UserAgent 中以用戶端提示為準的資料，通常不會是不準確的替代資訊，取代凍結或經過編輯的資訊。如果 User-Agent 標頭與根據 Client Hints 建立的 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 項目。這可能與 User-Agent 標頭和用戶端提示不相容，因此指定某些平台時可能需要測試兩個名稱。舉例來說，Apple 的 Macintosh 作業系統在 User-Agent 標頭中會標示為「Macintosh」，但在用戶端提示中則為「macOS」。以下說明根據 source 值，您可能會看到的其他差異：

  • USER_AGENT：version 欄位可能會縮減為主要版本或凍結。請注意，系統不會顯示值已凍結。
  • CLIENT_HINTS_LOW_ENTROPY：系統不會填入 version 欄位。
  • CLIENT_HINTS_HIGH_ENTROPY：version 欄位可設為完整版本。

行動裝置

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

架構

識別平台架構，例如「x86」或「arm」。

如果是以用戶端提示為依據的 UserAgent，請注意，只有在 source 設為 CLIENT_HINTS_HIGH_ENTROPY 時，系統才會填入這項資訊。

Bitness

識別平台位元數，例如 CPU 為 32 位元或 64 位元。這個欄位是整數字串，可提供架構的額外資訊；舉例來說，「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：可使用用戶端提示，包括至少一個分類為高熵的欄位。