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} 表示方法呼叫不會將目前的網頁納入主題的計算中。

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

您可以查看主題，並將網頁造訪次數標示為已觀察， request 和 回應標頭。

使用標頭方法的效果比使用 JavaScript API 更好，因為 API 需要建立跨來源 iframe，並從中發出 document.browsingTopics() 呼叫。(呼叫必須使用跨來源 iframe，因為系統是透過叫用 API 的內容，確保瀏覽器傳回適當的主題給呼叫端)。Topics 說明會進一步討論：是否能夠運用「擷取為要求標頭」來傳送主題？。

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

設定回應的 Observe-Browsing-Topics: ?1 標頭 會使瀏覽器依照呼叫端觀察到的時間點，記錄當前的網頁造訪。 以便日後用於計算主題

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

  • fetch()：將 {browsingTopics: true} 新增至 fetch() 要求的選項參數中。Topics 標題示範是簡化後的示例。
  • iframe 屬性：在 <iframe> 元素中加入 browsingtopics 屬性，或設定對等的 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 中一或多個主機名稱的主題 分類器模型所推測的主題。

chrome://topics-internals 頁面，已選取「Classifier」面板。
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
預設值：已啟用
啟用廣告 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
某個 Epoch 時間中的個別主題從來源隨機傳回的機率 整個分類 主題。隨機性會隨訓練週期和網站陷入停滯。

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
預設值：3
有多少週期的 API 使用資料 (即觀察主題) 篩選用於呼叫情境的主題

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 的所有網域。舉例來說，如要完全停止在除了您自己的來源和 https://example.com 以外的所有瀏覽環境內使用 Topics API，請設定以下 HTTP 回應標頭：

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

後續步驟

瞭解詳情

交流及分享意見回饋