Topics API 開發人員指南's 指南

瞭解如何使用 API，包括如何使用 Chrome 旗標進行測試。

導入狀態

立即試用

您可以透過兩種 Topics API 示範，以單一使用者的身分試用 Topics。

您也可以執行 Topics Colab，試用 Topics 分類器模型。

使用 JavaScript API 存取主題，並記錄為觀察到的主題

Topics JavaScript API 提供一種方法：document.browsingTopics()。這有兩個目的：

  • 指示瀏覽器將目前網頁造訪記錄為系統觀察到的呼叫端，以便之後用於計算使用者 (針對呼叫端) 的主題。
  • 存取呼叫端觀察到的使用者的主題。

此方法會傳回一個承諾，可解析為最多三個主題的陣列，以隨機順序解析最多三個主題中每個主題一個。週期是指一段時間，從 Chrome 導入作業設為一週。

document.browsingTopics() 所傳回陣列中的每個主題物件都具有下列屬性：

  • configVersion：識別目前 Topics API 設定的字串，例如 chrome.2
  • modelVersion：用於識別機器學習分類器的字串，用來推測網站的主題，例如 4
  • taxonomyVersion：用於識別瀏覽器使用主題組合的字串，例如 2
  • topic：識別分類中主題的數字，例如 309
  • version：串連 configVersion、taxonomyVersion 和 modelVersion 的字串，例如 chrome.2:2:4

隨著我們整合生態系統的意見回饋並反覆改進 API，本指南說明的參數，以及 API 的詳細資料 (例如分類大小、每週計算的主題數量和每次呼叫傳回的主題數量) 也隨時會有異動。

偵測 document.browsingTopics 支援

使用 API 前，請先檢查瀏覽器是否支援該 API，以及文件是否提供此功能：

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

使用 JavaScript API 存取主題

以下是可能的 API 使用情況，用於存取目前使用者主題的基本範例。

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

在不修改狀態的情況下存取主題

document.browsingTopics() 會傳回呼叫端觀察到目前使用者的主題。根據預設，此方法也會讓系統將呼叫端所觀察到的目前網頁造訪記錄下來，以便之後用於計算主題。從 Chrome 108 版開始，這個方法可傳送選用引數，略過網頁造訪記錄：{skipObservation:true}。

換句話說，{skipObservation:true} 表示方法呼叫不會將目前網頁納入主題計算中。

使用標頭存取主題，並將其標示為觀察項目

透過要求和回應標頭，您也可以存取主題，並將網頁造訪次數標示為觀察項目。使用標頭方法的效果會比呼叫 JavaScript API 好得多。

您可以透過 fetch() 或 XHR 要求的 Sec-Browsing-Topics 標頭存取主題。

在要求回應上設定 Observe-Browsing-Topics: ?1 標頭會讓瀏覽器記錄呼叫端觀察到的目前網頁造訪，以便之後用於計算主題。

透過 HTTP 標頭存取和觀察主題的方式有兩種：

  • fetch()：將 {browsingTopics: true} 新增至 fetch() 要求的選項參數。「主題標題示範」是簡要範例。
  • iframe 屬性：將 browsingtopics 屬性新增至 <iframe> 元素，或設定對等的 JavaScript 屬性 iframe.browsingTopics = true。iframe 來源的可註冊網域是呼叫端網域，例如 <iframe src="https://example.com" browsingtopics></iframe> 時，呼叫端是 example.com。

標題注意事項：

  • 系統會追蹤重新導向，而重新導向要求中傳送的主題只適用於重新導向網址。
  • 除非有對應的回應標頭，否則要求標頭不會修改呼叫端的狀態。也就是說，如果沒有回應標頭，系統就不會記錄網頁瀏覽，因此不會影響使用者下一個週期的主題計算。
  • 只有在相應要求包含主題標頭時，系統才會遵循回應標頭。
  • 要求的網址會提供可註冊為呼叫端網域的可註冊網域。

對 API 實作進行偵錯

啟用 Topics API 後，電腦版 Chrome 就會顯示 chrome://topics-internals 頁面。這個頁面會顯示目前使用者的主題、推測主機名稱的主題，以及 API 實作的相關技術資訊。我們會根據開發人員的意見反覆改進與改善網頁設計，請前往 bugs.chromium.org 提供意見。

查看系統根據瀏覽器計算的主題

使用者可以查看 chrome://topics-internals，查看瀏覽器在目前和上一個週期中觀察到的主題相關資訊。

chrome://topics-internals 頁面，已選取「主題狀態」面板。
chrome://topics-internals 頁面「主題狀態」面板會顯示主題 ID、隨機和實際主題的指派情形，以及分類和模型版本。

這張螢幕截圖顯示最近造訪過的網站包含「topics-demo-cats.glitch.me」和「cats-cats-cats-cats.glitch.me」。如此一來，Topics API 便會選取 Pets 和 Cats，做為目前週期的兩個熱門主題。剩下的三個主題已隨機選擇，因為沒有足夠的瀏覽記錄 (在觀察主題的網站上)，無法提供五個主題。

「觀察到的內容網域 (經雜湊處理)」欄會列出曾觀察到主題的主機名稱雜湊值。

查看系統推測的主機名稱主題

您也可以在 chrome://topics-internals 中，查看 Topics 分類器模型針對一或多個主機名稱推斷的主題。

chrome://topics-internals 頁面，已選取「分類器」面板。
chrome://topics-internals 頁面分類器面板會顯示已選取的主題、造訪過的主機，以及模型版本和路徑。

目前實作的 Topics API 只會從主機名稱推測主題，不會從網址的任何部分推斷主題。

僅使用主機名稱 (不含通訊協定或路徑) 來查看 chrome://topics-internals 分類器所推測的主題。如果您嘗試在主機欄位中加入「/」，chrome://topics-internals 就會顯示錯誤。

查看 Topics API 資訊

您可以在 chrome://topics-internals 中找到 Topics API 實作和設定的相關資訊，例如分類版本和訓練週期持續時間。這些值反映 API 的預設設定，或是透過指令列成功設定的參數。這有助於確認指令列旗標是否正常運作。

在這個範例中，time_period_per_epoch 已設為 15 秒 (預設為 7 天)。

chrome://topics-internals 頁面，已選取「功能和參數」面板。
「chrome://topics-internals 功能和參數」面板會顯示已啟用的功能、每個訓練週期所需時間、計算主題時要採用的週期數、分類版本和其他設定。

螢幕截圖中顯示的參數，與可透過指令列執行 Chrome 時可以設定的旗標對應。舉例來說，topics-fetch-demo.glitch.me 中的示範建議使用下列標記：

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

以下清單說明每個參數、參數的預設值和用途。

Chrome 旗標

BrowsingTopics
預設值：已啟用
指出是否啟用 Topics API。

PrivacySandboxAdsAPIsOverride
預設值：已啟用
啟用 Google Ads API：Attribution Reporting、Protected Audience、Topics、Fenced Frames。

PrivacySandboxSettings4
預設值：已停用
啟用第四個版本的 Privacy Sandbox UI 設定。

OverridePrivacySandboxSettingsLocalTesting
預設值：已啟用
如果啟用，瀏覽器就不會再要求基礎設定啟用 Privacy Sandbox 功能。

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
預設值：已停用
如果啟用這個選項，在決定將頁面納入主題計算的資格時，系統會略過 IP 位址是否可公開轉送。

BrowsingTopics:number_of_epochs_to_expose
預設值：3
從開始計算主題至要求背景的週期數。瀏覽器內部最多會保留 N+1 個週期。

BrowsingTopics:time_period_per_epoch
預設值：7d-0h-0m-0s
每個訓練週期的時間長度。如要進行偵錯，請將這個值設為 15 秒，而非預設的 7 天。

BrowsingTopics:number_of_top_topics_per_epoch
預設值：5
每週期計算的主題數量。

BrowsingTopics:use_random_topic_probability_percent
預設值：5
週期內的個別主題從整個主題的分類中隨機傳回的機率。隨機性是固定的週期和中心。

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
預設值： 3
系統會以多少訓練週期 (例如主題觀察項目) 來篩選呼叫情境的主題。

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
預設值：1000
每個熱門主題要保留的結構定義網域數量上限。這麼做是為了限制使用中的記憶體。

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
預設值：100000
系統為每項查詢的 API 使用情境，從資料庫擷取的項目數量上限。這項查詢會在每個訓練週期執行一次，以計算主題。這麼做是為了限制記憶體用量高峰。

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
預設值：30
每次載入網頁時，可儲存的 API 使用情境網域數量上限。

BrowsingTopics:config_version
預設值：1
對 Topics API 設定參數進行編碼。每個版本號碼應該只對應至一個設定集。一般來說，在不更新 config_version 的情況下更新設定參數，通常適用於本機測試，但在某些情況下，瀏覽器可能會處於不一致的狀態，並可能導致瀏覽器當機 (例如更新 number_of_top_topics_per_epoch)。

BrowsingTopics:taxonomy_version
預設值：1
API 使用的分類版本。

停用您的網站

如果不希望系統計算網站上特定網頁的主題，請在網頁中加入 Permissions-Policy: browsing-topics=() Permissions-Policy 標頭，這樣系統就只會對該網頁上的所有使用者進行主題計算。後續造訪網站上其他網頁並不會受到影響：如果將政策設為封鎖某個網頁上的 Topics API，則不會影響其他網頁。

您也可以使用 Permissions-Policy 標頭控管第三方的 Topics API 存取權，藉此控管哪些第三方有權存取你的網頁主題。做為標頭參數，請使用 self 以及您要授予 API 存取權的所有網域。舉例來說，如要完全停止在所有瀏覽環境中使用 Topics API (您來源和 https://example.com 除外)，請設定下列 HTTP 回應標頭：

Permissions-Policy: browsing-topics=(self "https://example.com")

後續步驟

瞭解詳情

交流及分享意見回饋