運用 Topics API 備妥使用、測試及開發網頁應用程式的環境。
在本機建構及測試
本節說明如何設定本機環境，以個別開發人員的身分試用 Topics API。實際導入前，建議您先查看示範瞭解 Topics 的運作方式。
在瀏覽器中啟用 Topics
如要在自己的 Chrome 例項中啟用 Topics API 進行本機測試，您有兩種方法：
- 啟用
chrome://settings/adPrivacy下的所有廣告隱私權 API。 - (建議做法) 使用 Topics API 專屬參數，透過指令列搭配 Chromium 旗標執行 Chrome，視需要進行設定。您可以透過指令列執行 Chrome，更精確地控管 Topics 功能。舉例來說，您可以設定 Topics 紀元 (API 用來計算使用者興趣的時間範圍)，並根據需求設定 API 行為。
重要建議
- 請務必先關閉並停止「所有」Chrome 處理程序，再使用旗標展開新的程序。
- 請確認已在
chrome://settings/adPrivacy下啟用所有廣告隱私權 API。 - 如果 API 無法正常運作，請嘗試我們的疑難排解提示。
- 如有任何疑問，請參閱 GitHub 問題相關說明。
使用 Chrome 旗標控管 Topics API
Chrome 標記可修改 Topics API 的行為。透過指令列執行 Chrome，並加上指定的參數，以便進行測試。舉例來說，標頭示範建議使用下列標記：
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
下表說明每個參數、其預設值和用途。
| 標記名稱 | 預設值 | 說明 |
|---|---|---|
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 | 某個週期中某個某個主題從整個分類中隨機傳回的機率。隨機值會與特定時段和網站綁定。 |
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 使用的分類版本。 |
導入前的準備
開始實作前，建議您先參閱下列資源來熟悉 Topics API。
- 查看開發人員說明文件：
- 瞭解 API 在支援廣告關聯性方面在日後扮演的角色，也就是在日後停止支援第三方 Cookie 的使用者。
- 如要收到 API 的狀態變更通知，請加入開發人員專用的郵寄清單，並密切留意 Topics 最新消息。
- 對 GitHub 問題或 W3C 通話參與對話。
- 如果您不熟悉某些術語，請參閱 Privacy Sandbox 專有名詞解釋。
- 如要進一步瞭解 Chrome 標記等 Chrome 概念，請前往 goo.gle/cc 觀看短片和文章。
