本頁面由 Cloud Translation API 翻譯而成。

Topics API 整合指南

瞭解如何使用 Topics API 滿足特定廣告技術用途。

事前準備

第一步是熟悉 Topics API 和服務。

查看開發人員說明文件：
1. 首先請參閱總覽，熟悉 Topics API 和相關功能。
2. 觀看 Topics 逐步操作說明 (影片)。
3. 試用 Topics 標頭和 JavaScript API 示範。
4. 分支 (兩者皆會提供程式碼連結) 並透過您的網站執行。
5. 閱讀 API 說明以瞭解詳情。
查看 Topics API 的導入狀態和時程。
瞭解 API 在在無 Cookie 的未來環境中支援廣告關聯性時所扮演的角色。
如要收到 API 的狀態變更通知，請加入開發人員專用的郵寄清單，並密切留意 Topics 最新消息。
隨時掌握 Topics API 的最新消息。
透過 GitHub 問題或 W3C 呼叫參與對話。
如果遇到不熟悉的字詞，請參閱 Privacy Sandbox 詞彙。
如要進一步瞭解 Chrome 標記等 Chrome 概念，請前往 goo.gle/cc 觀看短片和文章。

在本機建構及測試

本節說明如何以個別開發人員的身分試用 Topics API。

本機測試與部署 (預計時間：約 2 天)
1. 透過具有功能旗標的指令列，透過本機瀏覽器啟用 API。測試標頭和 JavaScript API 的示範，瞭解 Topics 的實際運作情形 (逐步操作說明影片)。
2. 執行 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。 — chrome://topics-internals 工具「主題狀態」分頁。

使用 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 採取的步驟。 — API 如何觀察及存取主題。

下圖：

使用者開啟 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)。

使用 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 要求存取主題。

設定及擷取主題的要求和回應標頭。 — iframe 和 `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 週) 來收集主題
1. 瞭解可用選項：iframe 和 JavaScript 或 HTTP 標頭
2. 定義 iframe 的網域。
3. 建構 JavaScript 程式碼，以試用版應用程式做為程式碼參考資料，或者實作標頭選項。
4. 將 Topics 部署至受控管的環境 (部分實際工作環境網站)。
5. 將 Topics 導入方式加進部分目標網站 (目前不超過五個網站)。
6. 功能測試和驗證。
[選用] 將主題資料做為比對內容信號 (含網址、標記等)(預估時間：約 3 天)。
1. 收到主題清單後，您可以將主題清單與其他比對內容訊號一起傳送至後端。

部署至部分目標網站

現在您已取得程式碼，讓我們可以將其新增至部分目標網站，以進行第一次的測試，並確認 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() 主題所需的時間，也是另一個要計算的指標。

疑難排解

我呼叫的是 Topics API，結果收到空值。該怎麼辦？: 如果您在觀察使用者後的第一個星期內呼叫 Topics API，這是正常現象。

重要建議

測試前端程式碼，確認您的 JavaScript 可正常運作。
測試後端以取得主題結果。
1. 請記得確保資料類型和後端 API 參數設定正確。
2. 確保後端已設定為適當縮放。
根據我們的經驗，您必須等待至少三週，才能開始取得更相關的主題結果。
並非所有使用者都能啟用 Topics：
1. 使用者可以明確停用 Topics API。
2. 發布商的網頁可控管權限政策。請參閱 Topics API 開發人員指南中的 (選擇不採用) 部分。
3. 詳情請參閱 chromestatus.com。
請在這個環境中新增指標和觀測能力，您需要這些指標才能分析第一項結果。範例指標包括：
1. 呼叫延遲時間；
2. 主題呼叫的 HTTP 錯誤；
在這三週內，盡量不要變更導入方式。

擴充至實際工作環境

以下的逐步摘要說明如何擴大至實際工作環境。這些步驟說明如下：

調度實作 (實際工作環境) 資源的說明如下。
1. 將 iframe 加入多個發布商的網站。
處理及使用主題資料 (預估時間：約 4 週)。
1. 將主題資料做為附加信號與其他資料一起整合。
2. 來源即時出價測試合作夥伴。
3. 執行公用程式測試，將主題視為其他資料的額外信號，並加以執行。

擴大實作規模

此時，您應該已在受控管的環境中從部分網站收集主題資料，並對整個解決方案更有信心。

現在，下一步是將相同的程式碼部署到更多目標網站，擴大導入範圍。這可讓您觀察更多使用者、收集更多主題資料，並加深對目標對象的瞭解。

建議您採取下列做法：

請在網站上逐步部署，尤其是在流量龐大時。
根據預期流量，針對主題資料執行負載測試。
1. 確認後端可處理大量呼叫。
2. 設定分析用的指標收集與記錄檔。
部署 Topics API 後，請立即檢查指標，偵測是否有任何嚴重的使用者問題。請持續定期查看指標。
如果系統出現中斷或非預期的行為，請復原部署作業並分析記錄檔，藉此瞭解並修正問題。

交流及分享意見回饋

GitHub：參閱 Topics API 說明工具，以及提出疑問並追蹤 API 存放區中相關問題。
W3C：前往「改善網路廣告業務群組」討論業界應用實例。
公告：加入或查看郵寄清單。
Privacy Sandbox 開發人員支援：在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
Chromium：請回報 Chromium 錯誤，針對目前可在 Chrome 中測試的實作問題提問。

Topics API 整合指南

事前準備

在本機建構及測試

在瀏覽器中啟用 Topics

預覽 Topics API 機制

API 如何傳回主題

重要建議

規劃 MVP 部署作業

呼叫 Topics API

使用 JavaScript 和 iframe 導入

使用 HTTP 標頭實作

透過 fetch() 導入

透過 iframe 導入

伺服器端 - 與所有情況相同

Topics 後端實作

使用主題做為內容比對資料

建構及部署

部署至部分目標網站

功能測試和驗證

疑難排解

重要建議

擴充至實際工作環境

擴大實作規模

交流及分享意見回饋

透過 `fetch()` 導入