瞭解如何使用 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}
表示方法呼叫不會將目前網頁納入主題計算中。
使用標頭存取主題,並將其標示為觀察項目
透過要求和回應標頭,您就可以存取主題,以及將網頁造訪標示為觀察項目。
使用標頭方法的成效可能會比使用 JavaScript API 要更高,因為 API 需要建立跨來源 iframe,並從這個 iframe 發出 document.browsingTopics()
呼叫。(因為呼叫 API 會使用結構定義,確保瀏覽器傳回適合呼叫端的主題,所以呼叫必須使用跨來源 iframe)。主題說明進一步探討了以下主題:是否有辦法使用「擷取做為要求標頭」傳送主題?
您可以透過 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 頁面,已選取「主題狀態」面板。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-0a0a54332c409.png?authuser=3&hl=zh-tw)
這張螢幕截圖顯示最近造訪過的網站包含「topics-demo-cats.glitch.me
」和「cats-cats-cats-cats.glitch.me
」。如此一來,Topics API 便會選取 Pets
和 Cats
,做為目前週期的兩個熱門主題。剩下的三個主題已隨機選擇,因為沒有足夠的瀏覽記錄 (在觀察主題的網站上),無法提供五個主題。
「觀察到的內容網域 (經雜湊處理)」欄會列出曾觀察到主題的主機名稱雜湊值。
查看系統推測的主機名稱主題
您也可以在 chrome://topics-internals
中,查看 Topics 分類器模型針對一或多個主機名稱推斷的主題。
![chrome://topics-internals 頁面,已選取「分類器」面板。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=3&hl=zh-tw)
目前實作的 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 頁面,已選取「功能和參數」面板。](https://developers.google.cn/static/privacy-sandbox/assets/images/chrometopics-internals-a56a143c41aa1.png?authuser=3&hl=zh-tw)
螢幕截圖中顯示的參數,與可透過指令列執行 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")
後續步驟
- 進一步瞭解主題的定義和運作原理。
- 立即試用示範。
瞭解詳情
交流及分享意見回饋
- GitHub:參閱 Topics API 說明工具,以及提出疑問並追蹤 API 存放區中相關問題。
- W3C:前往「改善網路廣告業務群組」討論業界應用實例。
- 公告:加入或查看郵寄清單。
- Privacy Sandbox 開發人員支援:在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
- Chromium:請回報 Chromium 錯誤,針對目前可在 Chrome 中測試的實作問題提問。