實作 Topics API

本頁說明 Topics API 呼叫端的實作詳細資料，方便觀察及存取主題。開始導入解決方案前，請先確認瀏覽器設定正確無誤。查看總覽部分，進一步瞭解通話者如何觀察及存取使用者的主題。

觀察及存取主題

觀察及存取使用者主題的方法有兩種：HTTP 標頭和 JavaScript API。

HTTP 標頭

建議使用 HTTP 標頭觀察及存取使用者主題。 這個方法的效能比使用 JavaScript API 高得多。使用 HTTP 標頭時，要求的網址會提供可註冊的網域，該網域會記錄為呼叫端網域。這個網域似乎已觀察到使用者的主題。

發起要求

使用標題搭配主題的方式有兩種：

  • 存取包含 browsingTopics: true 選項的 fetch() 要求中的要求和回應標頭。
  • 存取包含 browsingtopics 屬性的 iframe 元素標頭。
使用擷取作業啟動要求

使用 Fetch 時，API 呼叫端會發出要求，其中包含選項參數中的 {browsingTopics: true}。擷取要求網址參數的來源，是觀察到主題的來源。

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
使用 iframe 啟動要求

在 <iframe> 元素中新增 browsingtopics 屬性。瀏覽器會在 iframe 的要求中加入 Sec-Browsing-Topics 標頭，並將 iframe 的來源設為呼叫端。

   <iframe src="https://adtech.example" browsingtopics></iframe>

解讀要求標頭值

無論採用哪種方法 (擷取和 iframe)，都可以在伺服器上從 Sec-Browsing-Topics 要求標頭擷取觀察到的使用者主題。Topics API 會在 fetch() 或 iframe 要求中，自動將使用者主題納入標頭。如果 API 傳回一或多個主題，對觀察到主題的來源發出的擷取要求，就會包含類似這樣的 Sec-Browsing-Topics 標頭：

   (325);v=chrome.1:1:1, ();p=P000000000

如果 API 未傳回任何主題，標頭會如下所示：

   ();p=P0000000000000000000000000000000

系統會追蹤重新導向，且重新導向要求中傳送的主題會與重新導向網址相關。 Sec-Browsing-Topics 標頭值會經過填補，以降低攻擊者根據標頭長度，瞭解呼叫者範圍內主題數量的風險。

處理伺服器端回應

如果要求的回應包含 Observe-Browsing-Topics: ?1 標頭，表示瀏覽器應將隨附要求中的主題標示為已觀察，並將目前網頁造訪記錄納入使用者下一個時期主題的計算。在伺服器端程式碼的回應中加入 Observe-Browsing-Topics: ?1 標頭：

   res.setHeader('Observe-Browsing-Topics', '?1');
用於設定及擷取主題的要求和回應標頭。
iframe 和 fetch() 的標頭。

與合作夥伴分享觀察到的主題

由於供應端平台只會出現在發布商端，需求端平台可能會想與合作夥伴供應端平台分享在廣告主網站上觀察到的主題。他們可以從廣告主的頂層內容，向賣方平台發出含有主題標頭的 fetch() 要求。

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

使用 JavaScript 觀察及存取主題

Topics JavaScript API 方法 document.browsingTopics() 可在瀏覽器環境中觀察及擷取使用者的興趣主題： - 記錄觀察：通知瀏覽器呼叫端已觀察到使用者造訪目前網頁。這項觀察結果會納入使用者在未來 Epoch 時間的呼叫端主題計算。 - 存取主題：擷取呼叫端先前為使用者觀察到的主題。這個方法會傳回最多三個主題物件的陣列，每個物件代表最近一個週期，順序隨機。

建議您將 Topics JavaScript API 示範分叉，並做為程式碼的起點。

API 適用性

使用 API 前，請確認該 API 是否受支援且可用：

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

嵌入 iframe

呼叫時必須使用跨來源 iframe，因為系統會根據 API 的叫用環境，確保瀏覽器傳回適合呼叫端的相關主題。在 HTML 中加入 <iframe> 元素：

<iframe src="https://example.com" browsingtopics></iframe>

您也可以使用 JavaScript 動態建立 iframe：

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

從 iFrame 呼叫 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() 方法也會導致瀏覽器記錄呼叫端觀察到的目前網頁造訪記錄，以便稍後用於主題計算。這個方法可以傳遞選用引數，略過記錄網頁造訪：{skipObservation:true}。

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

瞭解回覆

系統最多會傳回三個主題：過去三週各一個或零個，視是否觀察到主題而定。系統只會傳回呼叫端觀察到的目前使用者主題。以下是 API 傳回的範例：

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion：字串，用於識別瀏覽器的主題演算法設定版本。
  • modelVersion：用於推斷主題的機器學習分類器 ID 字串。
  • taxonomyVersion：字串，用於識別瀏覽器使用的主題集。
  • 主題：用於識別分類中主題的數字。
  • 版本：串連 configVersion、taxonomyVersion 和 modelVersion 的字串。 本指南所述的參數和 API 詳細資料 (例如分類大小、每週計算的主題數量，以及每次呼叫傳回的主題數量) 可能會變更，因為我們會納入生態系統意見回饋並疊代 API。

請參閱「測試及上線」頁面，瞭解預期回應，以及如何使用主題做為額外信號，放送更切題的廣告。

後續步驟

瞭解如何部署、測試及擴大使用 Topics 的解決方案。
瞭解 Chrome 中可用於查看 Topics API 資訊的工具，以及如何指派主題和偵錯實作項目。

另請參閱

請參閱我們的資源，進一步瞭解 Topics API 在網路上的運作方式。