瞭解如何使用 API,包括如何使用 Chrome 標記進行測試。
導入狀態
- Topics API 已完成公開討論階段,目前開放 99% 的使用者使用,向上擴充至 100%。
- 如要提供你對 Topics API 的意見,請在 Topics 說明上建立問題,或參與改善網路廣告業務小組討論。解釋中有一些未解決的問題,但仍需進一步定義。
- Privacy Sandbox 時程表提供 Topics API 和其他 Privacy Sandbox 提案的導入時程。
- Topics API:最新更新內容詳細說明 Topics API 和實作方式的變更與改善項目。
立即試用
我們提供兩個 Topics API 示範,讓您以單一使用者的身分試用 Topics。
- JavaScript API 示範:topics-demo.glitch.me
- 標題示範:topics-fetch-demo.glitch.me
你也可以執行 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
,查看在目前和上一個週期期間觀察到的瀏覽器主題相關資訊。
這張螢幕截圖顯示最近造訪的網站包含 topics-demo-cats.glitch.me
和 cats-cats-cats-cats.glitch.me
。這會導致 Topics API 選擇 Pets
和 Cats
做為目前週期的兩個熱門主題。其餘三個主題是隨機選擇,因為瀏覽記錄不足 (查看主題的網站) 無法提供五個主題。
「觀察到的情境網域 (經雜湊處理)」欄會提供觀察到的主題主機名稱的雜湊值。
查看推測的主機名稱主題
您還可以查看 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-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")
後續步驟
- 進一步瞭解什麼是主題及運作方式。
- 立即試用示範功能。
瞭解詳情
交流及分享意見回饋
- GitHub:參閱 Topics API 說明工具,以及提出疑問並追蹤 API 存放區中相關問題。
- W3C:前往「改善網路廣告業務群組」討論業界應用實例。
- 公告:加入或查看郵寄清單。
- Privacy Sandbox 開發人員支援:在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
- Chromium:請回報 Chromium 錯誤,針對目前可在 Chrome 中測試的實作問題提問。