使用 Topics API

高層概覽

假設我們有一個廣告技術平臺 ad-tech1.example，它透過 <iframe> 將廣告嵌入到以下發布商網站中：

• yoga.example
• knitting.example
• football.example

如果 ad-tech1.example 中的 <iframe> 內容實現了支援 Topics API 的功能，那麼當每個網站載入時，瀏覽器將：

1. 從網站 URL 推斷興趣主題。主題來自標準分類法；對於上述 URL 示例，它們將是“健身”、“纖維與紡織藝術”和“足球”。
2. 標記已觀察到的主題，這涉及在私有主題歷史儲存中為每個主題記錄一個主題歷史記錄條目。每個主題歷史記錄條目包含以下資訊：
   • 文件 ID（即當前頁面的識別符號）。
   • 主題計算輸入資料（即頁面主機名）。
   • 首次觀察到該頁面的時間（自 Unix 紀元以來）。
   • 觀察到該主題的域（稱為主題呼叫方域）。

選擇興趣主題以影響廣告選擇

瀏覽器將持續地：

1. 跟蹤使用者在每個新時期內觀察每個主題的頻率。一個時期預設為一週，但為了測試目的，其長度可以更改（請參閱 測試提示）。

   Chrome 將分類法中的 22 個根主題（沒有祖先的主題）放入兩個儲存桶之一，表示對整個廣告技術生態系統具有較高或標準的效用。根主題的所有後代都繼承其父主題的相同儲存桶分配。根主題到儲存桶的分配基於 Google 從生態系統中的公司那裡收到的關於效用的輸入。

2. 在每個時期結束時，為每位使用者選擇最受歡迎的主題

   1. Chrome 將使用者瀏覽歷史中的呼叫方域主機名轉換為主題。
   2. 這些主題首先按儲存桶排序，然後按頻率（匹配主機名的次數）排序。也就是說，如果兩個主題在同一個儲存桶中但頻率不同，則頻率較高的主題排序更高。
   3. Chrome 在每個時期結束時選擇使用者最受歡迎的五個主題，這些主題有資格與呼叫方共享。

3. 只有當 ad-tech1.example 出現在每個主題的歷史記錄條目中儲存的呼叫方域列表中時，才會將最受歡迎的主題返回給 ad-tech1.example。

   注意： 最初，不會返回任何主題，因此 <iframe> 可能會顯示預設的非定向廣告。但是，一旦第一個時期結束，API 將開始返回主題，ad-tech1.example 就可以根據當前使用者的觀察主題開始顯示更相關的廣告。

然後，ad-tech1.example 會根據返回的主題選擇一個相關的廣告來投放給使用者。

哪些 API 功能支援 Topics API？

以下功能均具有雙重目的——它們將使用者最受歡迎的主題返回給呼叫方，並觸發瀏覽器將當前頁面訪問記錄為呼叫方已觀察到的，以便以後可以使用該頁面的主機名進行主題計算。為此，它們需要包含在呼叫廣告技術的 <iframe> 中；然後，該 <iframe> 必須嵌入到您希望觀察主題的頁面上。

• 您可以在對廣告技術平臺的 fetch() 呼叫中的選項物件中指定 browsingTopics: true 選項。

• 您也可以將 browsingTopics: true 傳遞給 Request() 建構函式呼叫的選項物件中，然後將生成的 Request 物件傳遞給 fetch() 呼叫。

• 您可以在 <iframe> 上設定 browsingtopics 屬性，同時或在設定 src 屬性以載入源之前。這可以這樣完成：

  • 在 HTML 中宣告式設定
  html

  <iframe browsingtopics src="ad-tech1.example"> ... </iframe>
  

  • 透過將等效的 HTMLIFrameElement.browsingTopics 屬性設定為 true 來以程式設計方式設定
  js

  const iframeElem = document.querySelector("iframe");
  iframeElem.browsingTopics = true;
  

傳送與上述功能之一相關的請求時：

1. 將傳送一個 Sec-Browsing-Topics 頭資訊，其中包含當前使用者最受歡迎的主題。

2. 廣告技術伺服器根據這些主題選擇一個相關的廣告來顯示在 <iframe> 中，並將顯示它所需的響應資料傳送回來。

3. 應在對請求的響應中設定一個 Observe-Browsing-Topics 頭資訊 — 這會使瀏覽器將當前頁面訪問記錄為呼叫廣告技術提供商已觀察到的，因此相關主題將被記錄在主題歷史記錄條目中，並隨後用於主題選擇。

   注意： 重要的是要澄清，這並不會記錄在 Sec-Browsing-Topics 頭資訊中傳送的最受歡迎的主題作為已觀察到的。它記錄的是從呼叫方網站的 URL（即嵌入廣告技術 <iframe> 的網站）推斷出的已觀察到的主題。

browsingTopics() 方法

或者，嵌入的 <iframe> 可以呼叫 Document.browsingTopics() 來返回使用者當前最受歡迎的主題，然後可以在後續的 fetch 請求中將其返回給廣告技術平臺。這不依賴於 HTTP 頭資訊，但效能稍差。建議您使用上面列出的 HTTP 頭資訊方法之一，僅在無法修改頭資訊的情況下回退到 browsingTopics()。

私有主題集

呼叫方只能訪問他們自己為使用者觀察到的主題，而不能訪問其他呼叫方觀察到的主題。例如：

• 如果 ad-tech1.example 平臺在 tennis.example 上嵌入了一個包含 Topics API 功能的 <iframe>，他們將觀察到訪問該網站的使用者的“運動”和“網球”等主題。
• 如果另一個廣告技術平臺 ad-tech2.example 在“gardening.example”上嵌入了一個 Topics API <iframe>，他們將觀察到“園藝”主題。

這些廣告技術平臺將只獲得他們觀察到的使用者的主題。在此示例中，ad-tech1.example 將不會獲得“園藝”，ad-tech2.example 也不會獲得“網球”。

換句話說，諸如廣告技術平臺之類的呼叫方只能獲得他們在某個頁面上有存在的主題。更重要的是，記錄的興趣主題是該 API 可訪問的唯一資訊 — 與跟蹤 cookie 不同，無法洩露任何其他資訊。

示例

使用 Document.browsingTopics()

// Get an array of topics for this user
const topics = await document.browsingTopics();

// Request an ad creative
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

將 browsingTopics 選項傳遞到 fetch()

// Request an ad creative
const response = await fetch("https://ads.example/get-creative", {
  browsingTopics: true,
});

// Get the JSON from the response
const creative = await response.json();

// Display ad

在 <iframe> 中包含 browsingtopics 屬性

<iframe browsingtopics src="ad-tech1.example"> ... </iframe>

測試提示

Chrome

觀察主題的預設時期長度為一週，這對於測試使用 Topics API 的程式碼來說太長了。為了在測試目的下縮短這個時間，在 Chrome 中，您可以透過如下方式使用功能標誌開啟瀏覽器：

BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s

有關如何執行此操作的更多資訊，請參閱 使用命令列開關執行 Chromium。

您還可以透過啟用以下 Chrome 開發者標誌，在無需註冊的情況下本地測試您的 Topics API 程式碼。

chrome://flags/#privacy-sandbox-enrollment-overrides

另見

• Topics API on privacysandbox.google.com (2023)