瞭解如何使用 Topics API 滿足特定廣告技術用途。
事前準備
第一步是熟悉 Topics API 和服務。
- 查看開發人員說明文件:
- 首先請參閱總覽,熟悉 Topics API 和相關功能。
- 觀看 Topics 逐步操作說明 (影片)。
- 試用 Topics 標頭和 JavaScript API 示範。
- 分支 (兩者皆會提供程式碼連結) 並透過您的網站執行。
- 閱讀 API 說明以瞭解詳情。
- 查看 Topics API 的導入狀態和時程。
- 瞭解 API 在在無 Cookie 的未來環境中支援廣告關聯性時所扮演的角色。
- 如要收到 API 的狀態變更通知,請加入開發人員專用的郵寄清單,並密切留意 Topics 最新消息。
- 隨時掌握 Topics API 的最新消息。
- 透過 GitHub 問題或 W3C 呼叫參與對話。
- 如果遇到不熟悉的字詞,請參閱 Privacy Sandbox 詞彙。
- 如要進一步瞭解 Chrome 標記等 Chrome 概念,請前往 goo.gle/cc 觀看短片和文章。
在本機建構及測試
本節說明如何以個別開發人員的身分試用 Topics API。
- 本機測試和部署 (預計時間:約 2 天)
- 透過具有功能旗標的指令列,透過本機瀏覽器啟用 API。測試標頭和 JavaScript API 的示範,瞭解 Topics 的實際運作情形 (逐步操作說明影片)。
- 執行 Topics Colab,使用 Topics 機器學習模型測試主題推論。
在瀏覽器中啟用 Topics
如要在自己的 Chrome 執行個體中啟用 Topics API 以進行本機測試,您可以採用以下兩種方法:
- 啟用
chrome://settings/adPrivacy
下的所有廣告隱私權 API。 - (建議做法) 使用 Topics API 專屬參數,透過指令列搭配 Chromium 旗標執行 Chrome,視需要進行設定。
您可以透過指令列執行 Chrome,更精確地控管 Topics 功能。舉例來說,您可以設定 Topics 週期 (API 用來計算使用者興趣的時間範圍),並根據您的需求設定 API 的行為。
預覽 Topics API 機制
您可以使用 chrome://topics-internals 工具,在本機查看基礎 Topics API 機制。
![前往 chrome://topics-internals 深入瞭解 Topics API。](https://developers.google.cn/static/privacy-sandbox/assets/images/take-look-inside-topics-c068f9e4e8454.png?authuser=7&hl=zh-tw)
使用 Topics API 內部工具,根據你造訪的網站在本機測試分類器。
這項工具可讓您查看:
- Topics State (主題狀態):顯示針對目前使用者觀察到的主題。
- 分類器:推測主機名稱的預覽主題。
- 功能與參數:查看 API 參數值,確認功能旗標正常運作。
瞭解如何使用內部工具偵錯 Topics。
API 如何傳回主題
如果 Chrome 觀測到的主題數量不足以根據某個週期建立前五項主題 (也就是一週),Topics API 就會新增隨機主題來完成前五項主題。「主題內部」欄的標題為「自然」或「隨機」,表示該主題是基於真實觀察還是其他隨機「邊框間距」來完成前五名。如要進一步瞭解這項機制,請參閱這份說明。
系統會在每段訓練週期內推測出使用者的五大偏好,並從中隨機選出一項做為該週期的主題。如果在訓練週期期間觀察到的主題數量不足,系統將會隨機選擇其他主題,加總五個元素。這些隨機選取的主題必須受到篩選。
為了進一步強化隱私權並確保所有主題能夠加以呈現,系統有 5% 的機率會從所有主題中隨機選出該週期的主題,而非從觀察主題中選出。如同上述例子中觀察到的主題過少,這些隨機選取的主題不會受到篩選。
如要進一步瞭解主題選項,請參閱「主題分類」。
重要建議
- 請務必先關閉 (並停止) 所有 Chrome 程序,再使用旗標展開新版程序。
- 確認
chrome://settings/adPrivacy
已啟用所有廣告隱私權 API。 - 使用偵錯頁面瞭解 Topics 在本機的運作方式。
- 如有任何問題,請參閱相關說明的 GitHub 問題。
- 如果 API 無法正常運作,請嘗試我們的疑難排解提示。
規劃 MVP 部署作業
Topics API 可用來存取觀察到的使用者感興趣的主題,而不必追蹤使用者造訪的網站或顯示瀏覽記錄。
Topics API「呼叫端」是指呼叫 document.browsingTopics()
JavaScript 方法的實體,或使用 HTTP 要求標頭觀察及存取主題。您的程式碼和呼叫的 eTLD+1 則為呼叫端。當您呼叫 Topics API 時,會指示使用者的瀏覽器在使用者造訪網站時觀察感興趣的主題。並在計算下一個週期的主題時將這次造訪納入考量。
Topics API 可以用來篩選呼叫情境的個別呼叫端結果或每個呼叫端的 Per-TLD+1。換句話說,系統會將 iframe 的來源 (使用 JavaScript API 時) 或擷取要求的網址 (使用標頭時) 視為呼叫端,並根據該呼叫端計算主題。
下圖說明瞭這項做法:
![在使用者造訪使用 API 的網站時,Topics API 採取的步驟。](https://developers.google.cn/static/privacy-sandbox/assets/images/the-steps-topics-api-tak-d1a397a6459c9.png?authuser=7&hl=zh-tw)
下圖:
- 使用者開啟 Chrome 並造訪多個網站 (customerA.example、customerB.example.br 等),其中包含您廣告技術的 iframe (來源:iframe.adtech.example) 或擷取呼叫傳遞標頭。
- Chrome 會記錄這位使用者感興趣的主題。
- 瀏覽 7 天後,Topics API 觀察到感興趣的主題後,同一使用者在同一部裝置上會造訪目標網站 (例如發布商網站)。Topics API 會傳回主題清單,在這個範例中,系統會傳回一個主題,根據該使用者前一週的觀察結果計算而得。
- 只有曾瀏覽步驟 1 中觀察到的網站使用者的瀏覽器,才會在步驟 2 傳回主題結果 (我們稱之為觀察篩選功能,您無法查看從未看過的使用者主題)。
- 透過這份清單 (目前只有一個主題),您可以呼叫後端 API (ads.adtech.example/topics-backend),以使用主題資料做為內容相關資料集。
- 現在,視你的用途而定,你可以存取過去幾週觀察到的使用者感興趣的主題,為他們打造更貼近個人需求的體驗。
呼叫 Topics API
觀察及存取使用者主題的方法有兩種。切換為
- 在 iframe 內執行 JavaScript API:
- 在包含使用
document.browsingTopics()
呼叫 Topics API 的 JavaScript 程式碼目標網站 (發布商的網站) 上加入 iframe。
- 在包含使用
- 標頭選項:
- 擷取 (建議使用) 或 XHR (不建議,並且只能在完成來源試用期間使用):
- 您可以在向廣告技術後端發出的請求中,存取
Sec-Browsing-Topics
標頭中的主題。這是成效最高的選項 (為了觀察特定使用者的主題,延遲時間較短)。
- 您可以在向廣告技術後端發出的請求中,存取
- 使用含
browsingtopics
屬性的 iframe 標記:- 您可以新增含有
browsingtopics
屬性的 iframe,而 Chrome 會在 iframe 要求的Sec-Browsing-Topics
標頭中加入主題 (觀察 iframe 的 eTLD+1)。
- 您可以新增含有
- 擷取 (建議使用) 或 XHR (不建議,並且只能在完成來源試用期間使用):
使用 JavaScript 和 iframe 導入
建議您建立 Topics JavaScript API 示範或標題示範,並以下列其中一種方式著手編寫程式碼。
您可以在 HTML 中加入 <iframe>
元素,或是使用 JavaScript 動態新增 iframe。想要動態建立 iframe,其中一種方式是使用以下 JavaScript:
const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);
可透過功能偵測確認裝置是否支援 Topics 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');
從該 iframe 內呼叫 Topics API:
const topics = await document.browsingTopics();
您應該會收到一份清單,其中列出過去三週為這位使用者觀察到的主題。請注意,這份清單可以留空,或包含過去三週的 1、2 或 3 個主題。
以下是 API 傳回內容的範例:
[{'configVersion': String,
'modelVersion': String,
'taxonomyVersion': String,
'topic': Number,
'version': String}]
- configVersion:用來識別目前設定的字串。
- modelVersion:這個字串可識別用來推斷主題的機器學習分類器。
- taxonomyVersion:這個字串可識別瀏覽器目前使用的主題集。
- topic:這是用於識別分類中主題的編號。
- version:結合
configVersion
和modelVersion
的字串。
如要進一步瞭解這項實作,請參閱本文。
使用 HTTP 標頭實作
系統可透過 extract()/XHR 要求的 Sec-Browsing-Topics
標頭或 iframe
要求存取主題。
![設定及擷取主題的要求和回應標頭。](https://developers.google.cn/static/privacy-sandbox/assets/images/request-response-headers-9b111b7c02dfb.png?authuser=7&hl=zh-tw)
fetch()
的標題。您可以將要求標頭提供的主題標示為已觀察,只要在要求回應上設定 Observe-Browsing-Topics: ?1
標頭即可。瀏覽器就會根據這些主題,計算使用者的興趣主題。
如果 API 傳回一或多個主題,針對觀察到主題的 eTLD+1 擷取要求,將包含類似下方的 Sec-Browsing-Topics
標頭:
(325);v=chrome.1:1:1, ();p=P000000000
如果 API 未傳回任何主題,標頭看起來會像這樣:
();p=P0000000000000000000000000000000
系統會在 Sec-Browsing-Topics
標頭值中填充值,降低攻擊者根據標頭長度瞭解範圍限定為呼叫端的主題數量。
透過 fetch()
導入
在發布商網頁上,新增擷取要求的程式碼,請務必加入 {browsingTopics: true}
。
fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
.then((response) => {
// Process the response
})
在支援 API 的瀏覽器中,fetch()
要求會包含 Sec-Browsing-Topics
標頭,列出觀察到的要求網址主機名稱主題。
透過 iframe 導入
與 fetch()
要求類似,在 iframe 上使用 browsingtopics
屬性時,系統也會傳送 Sec-Browsing-Topics
標頭。
<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>
在這種情況下,
會是呼叫端,類似擷取呼叫。
伺服器端 - 與所有情況相同
如要讓瀏覽器將 Sec-Browsing-Topics
要求標頭中的主題標示為觀察到,並將目前網頁造訪納入使用者下一個週期熱門主題的計算,伺服器的回應就必須包含 Observe-Browsing-Topics: ?1
。
以下是使用 setHeader()
的 JavaScript 範例:
res.setHeader('Observe-Browsing-Topics', '?1');
Topics 後端實作
您可以自行選擇是否要新增 Topics 後端。請根據裝置端 (在瀏覽器中) 計算主題的方式和位置來選擇合適的選項。
// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
// Validate inputs
// If the list is not empty, continue
// Use topics as an additional contextual signal
}
使用主題做為內容比對資料
您可以將主題資料與其他信號 (例如網址、關鍵字和標記) 搭配使用,做為目標對象的額外信號。
如「在使用第三方 Cookie 盡可能提高廣告關聯性」一文所述,您可以透過多種方法利用 Topics 放送相關廣告。這類做法包括用主題建立目標對象,有些則是建議將「主題」做為信號來訓練機器學習模型,進而推斷目標對象的其他興趣,甚至改善出價邏輯。
建構及部署
- 觀察正式環境中但尚未調整的使用者 (預計時間:約 1 週) 來收集主題
- 瞭解可用選項:iframe 和 JavaScript 或 HTTP 標頭
- 定義 iframe 的網域。
- 建構 JavaScript 程式碼,以試用版應用程式做為程式碼參考資料,或者實作標頭選項。
- 將 Topics 部署至受控管的環境 (部分實際工作環境網站)。
- 將 Topics 導入方式加進部分目標網站 (目前不超過五個網站)。
- 功能測試和驗證。
- [選用] 將主題資料做為比對內容信號 (含網址、標記等)(預計時間:約 3 天)。
- 收到主題清單後,您可以將主題清單與其他比對內容訊號一起傳送至後端。
部署至部分目標網站
現在您已取得程式碼,讓我們可以將其新增至部分目標網站,以進行第一次的測試,並確認 API 穩定運作,並且可在這個受控管的環境中運作。
建議選擇符合下列條件的網站:
- 每月獲得的造訪量偏低 (每月不到 100 萬次造訪):建議您先為少數目標對象部署 API。
- 您擁有且掌控權:必要時,您可以在不複雜核准的情況下快速停用該導入方式。
- 不太重要的業務:這種導入方式可能會幹擾使用者體驗,因此請先從低風險的目標網站著手。
- 最多五個網站:你暫時不需要太多流量或曝光率。
- 呈現不同主題:選擇屬於不同類別的網站,例如體育相關內容、新聞,或是美食和飲料的另一個主題網站。您可以使用 Chrome 的內部主題工具來驗證網域,以及網域被 Topics 機器學習分類器分類。如要進一步瞭解偵錯功能,請參閱 Topics API 開發人員指南。
功能測試和驗證
在這個受限的環境中呼叫 Topics API 時,您會發現:
- 如果這是這部裝置的第一次呼叫,且過去 7 天內的呼叫者是此裝置的第一組呼叫,則為
[]
的空白主題陣列。 - 包含 0 到 3 個主題的清單,代表這位使用者的興趣。
- 觀察七天後,您應該會收到:
- 從當週的導覽記錄計算而得的一個主題,代表使用者的興趣。
- 重要注意事項:如果 Topics API 的觀察結果不足,導致使用者無法計算該週的前五大主題,Topics 會視情況加入隨機主題,以達到前五個主題。進一步瞭解 API。
- 從當週的導覽記錄計算而得的一個主題,代表使用者的興趣。
- 一個新主題項目取代其中一個主題,會在觀察四週後呼叫這個方法。
- 這是因為 Topics API 在接下來幾週會保持穩定,不會顯得太多使用者興趣。前往 GitHub 瞭解詳情。
- 如果超過三週都沒有觀察到使用者的主題,Topics API 會再次傳回空白陣列
[]
。
評估使用者體驗的效能和指標。
- 請評估在跨來源 iframe 中對 Topics API 發出的 JavaScript 呼叫執行時間,以便日後進行效能分析。請務必在後端收集並儲存遙測資料。
- 收到主題後,建立 iframe 和
postMessage()
主題所需的時間,也是另一個要計算的指標。
- 收到主題後,建立 iframe 和
疑難排解
- 我呼叫的是 Topics API,結果收到空值。該怎麼辦?
- 如果您在觀察使用者的第一週內呼叫 Topics API,就可預期這種情況。
重要建議
測試前端程式碼,確認您的 JavaScript 可正常運作。
測試後端以取得主題結果。
- 請記得確保資料類型和後端 API 參數設定正確。
- 確保後端已設定為適當縮放。
根據我們的經驗,您必須等待至少三週,才能開始取得更相關的主題結果。
並非所有使用者都能啟用 Topics:
- 使用者可以明確停用 Topics API。
- 發布商的網頁可控管權限政策。請參閱 Topics API 開發人員指南中的 (選擇不採用) 部分。
- 詳情請參閱 chromestatus.com。
請在這個環境中新增指標和觀測能力,您需要這些指標才能分析第一項結果。範例指標包括:
- 呼叫延遲時間;
- 主題呼叫的 HTTP 錯誤;
在這三週內,盡量不要變更導入方式。
擴充至實際工作環境
以下的逐步摘要說明如何擴大至實際工作環境。這些步驟說明如下:
- 擴充實作 (正式環境) 資源的說明,如下所述。
- 將 iframe 加入多個發布商的網站。
- 處理及使用主題資料 (預估時間:約 4 週)。
- 將主題資料做為附加信號與其他資料一起整合。
- 來源即時出價測試合作夥伴。
- 執行公用程式測試,將主題視為其他資料的額外信號,並加以執行。
擴大實作規模
此時,您應該已在受控管的環境中從部分網站收集主題資料,並對整個解決方案更有信心。
現在,下一步是將相同的程式碼部署到更多目標網站,擴大導入範圍。這可讓您觀察更多使用者、收集更多主題資料,並加深對目標對象的瞭解。
建議您採取下列做法:
- 請在網站上逐步部署,尤其是在流量龐大時。
- 根據預期流量,針對主題資料執行負載測試。
- 確認後端可處理大量呼叫。
- 設定分析用的指標收集與記錄檔。
- 部署 Topics API 後,請立即檢查指標,偵測是否有任何嚴重的使用者問題。請持續定期查看指標。
- 如果系統出現中斷或非預期的行為,請復原部署作業並分析記錄檔,藉此瞭解並修正問題。
交流及分享意見回饋
- GitHub:參閱 Topics API 說明工具,以及提出疑問並追蹤 API 存放區中相關問題。
- W3C:前往「改善網路廣告業務群組」討論業界應用實例。
- 公告:加入或查看郵寄清單。
- Privacy Sandbox 開發人員支援:在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
- Chromium:請回報 Chromium 錯誤,針對目前可在 Chrome 中測試的實作問題提問。