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

Topics API 整合指南

瞭解如何根據特定的廣告技術用途，使用 Topics API。

事前準備

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

參閱開發人員說明文件：
1. 請先詳閱總覽，熟悉 Topics API 和相關功能。
2. 觀看「主題示範逐步操作說明」(影片)。
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 機器學習模型測試主題推論。

在瀏覽器中啟用主題

如要在自己的 Chrome 執行個體中啟用 Topics API 以進行本機測試，方法有以下兩種：

開啟 chrome://flags/#privacy-sandbox-ads-apis 並啟用 Privacy Sandbox API。
(建議做法) 視需要使用 Topics API 專屬參數，透過指令列搭配 Chromium 旗標執行 Chrome。

前往 chrome://flags/#privacy-sandbox-ads-apis 啟用 Privacy Sandbox API。 — 啟用 Privacy Sandbox API。

您可以透過指令列執行 Chrome，以便更精細地控管 Topics 功能。舉例來說，您可以設定 Topics 週期 (API 用來計算使用者興趣的時間範圍)，並根據需求設定 API 的行為。

請務必記住，如果 chrome://flags/#privacy-sandbox-ads-apis 已啟用，則會覆寫指令列週期設定，進而還原為預設值 (目前為一週)。

預覽 Topics API 機制

您可以透過 chrome://topics-internals 工具在本機查看基礎的 Topics API 機制。

歡迎前往 chrome://topics-internals 深入瞭解 Topics API。 — chrome://topics-internals 工具的「主題狀態」分頁。

使用 Topics API 內部工具，根據你造訪的網站在本機測試分類器。

這項工具可讓您查看：

主題狀態：顯示系統針對目前使用者觀察到的主題。
分類器：針對主機名稱推測的預覽主題。
功能和參數：查看 API 參數值，檢查功能旗標是否正常運作。

瞭解如何使用內部工具對 Topics 進行偵錯。

API 傳回主題的方式

如果 Chrome 的觀察主題數量不足，無法為一段訓練週期 (一週) 建立前五大主題，Topics API 就會隨機加入主題，用來完成前五大主題。標題為「Real 或 Random」的 Topics 內部如要進一步瞭解這項機制，請參閱說明。

系統會在每段訓練週期內推測出使用者的五大偏好，並從中隨機選出一項做為該週期的主題。如果我們在該週期期間觀察到的主題數量不足，則系統會隨機選擇其他主題，以共同達到五種。這些隨機選取的主題會經過篩選。

為進一步強化隱私權，並確保所有主題都能呈現，在訓練週期中隨機選擇的主題會有 5% 的機率會從所有主題中隨機選出，而非從觀察到的主題中挑選。就像上面這個情況一樣，系統觀察到的主題太少，因此隨機選出的主題不會經過篩選。

如要進一步瞭解如何選擇主題，請參閱「主題分類」一文。

重要建議

使用旗標開始新的 Chrome 程序前，請務必先關閉 (並停止) 所有程序。
如要在本機環境中進行測試，請停用 chrome://flags/#privacy-sandbox-ads-apis，因為這會覆寫指令列設定，還原為預設值。
如要瞭解 Topics 在本機的運作方式，請使用偵錯頁面。
如有任何疑問，請查看說明的 GitHub 問題。
如果 API 無法正常運作，請參閱我們的疑難排解提示。

規劃 MVP 部署

Topics API 可讓使用者存取系統觀察到的興趣主題，不必另外追蹤使用者造訪的網站，也不用公開他們的瀏覽記錄。

Topics API 呼叫器是呼叫 document.browsingTopics() JavaScript 方法的實體，或使用 HTTP 要求標頭觀察及存取主題的實體。您的程式碼和呼叫的 eTLD+1 就是呼叫端。呼叫 Topics API 時，您需要指示使用者的瀏覽器在造訪網站時觀察興趣主題。在計算下一個週期的主題時，系統會將這次造訪納入考量。

Topics API 旨在根據呼叫情境的每位呼叫端或每個-eTLD+1 篩選結果。換句話說，系統會將 iframe (使用 JavaScript API 時) 來源或擷取要求網址 (使用標頭時) 的來源視為呼叫端，並根據該呼叫端計算主題。

下圖說明這種方法：

Topics API 會在使用者造訪使用 API 的網站時採取的步驟。 — API 如何觀察及存取主題。

在此圖表中：

使用者開啟 Chrome 並造訪多個網站 (customerA.example、customerB.example.br 等)，其中包含廣告技術的 iframe (來源：iframe.adtech.example) 或擷取呼叫傳遞標頭。
- Chrome 會記錄這位使用者感興趣的主題。
7 天過後，由於 Topics API 偵測到興趣主題，同一部同部裝置使用者就會造訪目標網站 (發布商範例)。Topics API 會傳回主題清單，在此具體範例中，系統會傳回從該使用者前一週觀察結果計算得出的主題。
- 只有在使用者造訪了 adtech.example 曾在步驟 1 中觀察到的網站時，瀏覽器才會傳回步驟 2 的結果 (我們稱之為觀察篩選條件，您無法查看之前從未看過的使用者主題)。
有了這份清單 (目前只有一個主題)，您可以呼叫後端 API (ads.adtech.example/topics-backend)，以使用主題資料做為內容比對資料集的一部分。
現在，您可以根據自身的使用情況，存取過去幾週內觀察到的興趣主題，為這位使用者提供更貼近個人需求的體驗。

呼叫 Topics API

您可以透過兩種方式觀察及存取使用者的主題。切換為

iframe 中的 JavaScript API：
- 在目標網站 (發布商的網站) 上加入 iframe，其中包含使用 document.browsingTopics() 呼叫 Topics API 的 JavaScript 程式碼。
標頭選項：
- 擷取 (建議使用) 或 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 標頭導入

您可以透過擷取()/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 放送相關廣告。其中部分技巧是使用主題建立目標對象，有些則建議搭配使用 Topics 與其他信號，訓練機器學習模型，以便推論目標對象的其他興趣，甚至改善出價邏輯。

建構及部署

透過觀察實際工作環境中的使用者收集主題資料，但尚未擴大規模 (預估時間：約 1 週)
1. 瞭解選項：iframe 和 JavaScript 或 HTTP 標頭
2. 定義 iframe 的網域。
3. 建構 JavaScript 程式碼 (使用試用版應用程式做為程式碼參考資料)，或是導入標頭選項。
4. 將 Topics 部署至您控管的環境 (部分生產網站)。
5. 在部分目標網站 (目前不超過 5 個網站) 中加入主題導入。
6. 功能測試及驗證。
[選用] 使用 Topics 資料做為比對內容信號 (包含網址、標記等)(預計時間：約 3 天)。
1. 收到主題清單後，就能以其他比對內容訊號將內容傳送至後端。

部署至某些目標網站

現在您已取得程式碼，讓我們先將其新增至某些目標網站，以進行初步測試，並確保 API 穩定且可在受控管的環境中正常運作。

建議您選擇符合以下描述的網站：

每月取得少量造訪 (每月不到 100 萬次造訪)：建議您先先針對小型目標對象部署這個 API。
一切由您掌控：如有需要，您可以快速停用實作程序，不必經過複雜核准。
不是關鍵業務：由於這項導入方式可能會影響使用者體驗，因此請從低風險目標網站著手。
網站總數不超過 5 個：暫時不需要這類流量或曝光率。
代表不同主題：選擇代表不同類別的網站 (例如一個與運動相關的網站，另一個與新聞有關，另一個則與飲食主題有關)。您可以使用 Chrome 的內部主題工具來驗證網域，以及 Topics 機器學習分類器的分類方式。如要進一步瞭解偵錯，請參閱 Topics API 開發人員指南。

功能測試和驗證

在這個有限的環境中呼叫 Topics API 時，您可以預期會發生以下情況：

如果這是此裝置首次呼叫此網站以及過去七天內呼叫者，則為空白的主題陣列 []。
列出零到三個主題，代表使用者的興趣。
七天過後，您應該會收到：
- 根據當週的瀏覽記錄計算的使用者興趣的主題。
  - 重要注意事項：如果系統觀察到的使用者主題不足，導致 Topics API 無法計算當週的前五大主題，那麼 Topics API 會視需要加入任意數量的隨機主題，以達到共五項。進一步瞭解 API。
如果您在經過四週的觀察後呼叫，則取代三個新的主題項目。
- 這是因為 Topics API 在接下來的幾週將保持穩定，不會公開太多使用者的興趣。前往 GitHub 瞭解詳情。
如果您超過三週仍未觀察到使用者的主題，Topics API 會再次傳回空白陣列 []。

評估使用者體驗的成效和指標。

在跨來源 iframe 中對 Topics API 呼叫 Topics API 的執行時間應評估，並用於日後的成效分析。請務必妥善收集遙測資料，並儲存至後端。
- 系統收到主題後，建立 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 API 機制

API 傳回主題的方式

重要建議

規劃 MVP 部署

呼叫 Topics API

使用 JavaScript 和 iframe 導入

使用 HTTP 標頭導入

使用 fetch() 導入

使用 iframe 導入

伺服器端 - 適用於所有情況

Topics 後端實作

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

建構及部署

部署至某些目標網站

功能測試和驗證

疑難排解

重要建議

擴充至正式環境

大規模導入

交流及分享意見回饋

使用 `fetch()` 導入