指定使用者代理程式

過去，User-Agent 標頭會納入出價要求，提供實用的指定目標資料，例如啟動裝置的瀏覽器和平台。不過，由於使用者代理程式難以使用，且為了更好地保護使用者隱私，瀏覽器通常會大幅遮蓋使用者代理程式。為因應這個問題，Google 支援User-Agent Client Hints，並在可用時將其納入出價要求，以補充 User-Agent 標頭。這些用戶端提示 (簡稱) 可來自 Sec-Ch-UA* 標頭或 JavaScript 用戶端提示 API。

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

UserAgent 訊息會在 Client Hints 可用時填入 Client Hints，否則會根據從 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

如果至少包含低熵 Client Hints，即使有 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 通常會根據 User-Agent 標頭或用戶端提示，在 UserAgent 之間有所差異。舉例來說，如果 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”]，因為這是 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 項目。這可能與 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 時，才會填入這個值。

位元

識別平台的位元數，例如是否具有 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：可使用用戶端提示，其中至少有一欄位歸類為高熵。