Protected Audience API：開發人員指南

開發人員指南：裝置端廣告競價，用於放送再行銷廣告和自訂目標對象，不必跨網站追蹤第三方。

如果您是 Protected Audience API 的新手，請參閱 Protected Audience API 總覽，瞭解 API 的概略說明。

這篇文章是為開發人員撰寫，提供實驗版 Protected Audience API 最新版本的技術參考資料。您可以參考基本 Protected Audience API 部署的示範，以及廣告買家和賣家的 API 參考資料。

導入狀態

如要接收 API 狀態變更的通知，請加入開發人員的郵寄清單。

Protected Audience API 簡介

Protected Audience API 是一種 Privacy Sandbox API，設計目的是放送再行銷和自訂目標對象用途，並防止第三方追蹤使用者跨網站的瀏覽行為。這個 API 可讓瀏覽器進行裝置端競價，為使用者先前造訪的網站選擇相關廣告。

Protected Audience API 是 TURTLEDOVE 系列提案中，在 Chromium 中實作的首個實驗。

試用 Protected Audience API

可用的 API 參考資料

本文件概要說明 Protected Audience API。如果您想查看特定 API 方法和參數：

您也可以參閱 Protected Audience API 廣告競價延遲時間最佳做法。

Protected Audience API 範例

如要瞭解如何在廣告客戶和發布商網站上部署基本 Protected Audience API，請前往 protected-audience-demo.web.app/。

觀看這部端對端部署影片，瞭解 Protected Audience API 示範程式碼的運作方式，以及如何使用 Chrome 開發人員工具進行除錯。

測試這個 API

您可以在電腦上使用 Chrome Beta 101.0.4951.26 以上版本，為單一使用者測試 Protected Audience API：

在 iframe 或區隔的框架中顯示廣告

廣告可在 <iframe> 或 <fencedframe> 中顯示，具體取決於設定的標記。

如要使用 <fencedframe> 轉譯廣告，請按照下列步驟操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

如要使用 <iframe> 轉譯廣告，請按照下列步驟操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

加入 BiddingAndScoringDebugReportingAPI 標記，即可啟用暫時性偵錯損失/勝利回報方法。

支援的功能

在 Chromium 中，Protected Audience API 的功能旗標是第一個用於測試 Protected Audience API 以下功能的實驗：

  • 興趣群組：由瀏覽器儲存，並附帶相關中繼資料，用於設定廣告出價和顯示。
  • 買方 (需求端平台或廣告主) 在裝置端出價：根據儲存的興趣群組和賣方提供的信號。
  • 賣方 (SSP 或發布商) 的裝置端廣告選擇程序：根據競價出價和買方提供的中繼資料。
  • 在暫時放寬的 Fenced Frames 版本中顯示廣告：允許廣告顯示功能存取網路和記錄。

如要進一步瞭解功能支援和限制，請參閱 Protected Audience API 說明。

興趣群組權限

目前 Protected Audience API 的實作方式預設為允許從網頁中的任何位置，甚至是跨網域 iframe 中，呼叫 joinAdInterestGroup()。

日後，當網站擁有者有時間更新跨網域 iframe 權限政策後，我們將禁止跨網域 iframe 的呼叫。

鍵/值服務

為了支援 Protected Audience API 廣告競價，瀏覽器可以存取 鍵/值服務，擷取支援 Protected Audience API 廣告競價的即時資訊。這項資訊可用於多種用途：

  • 買方可能需要計算廣告活動中的剩餘預算。
  • 賣方可能需要檢查廣告素材是否符合發布商政策。

Protected Audience API 鍵/值服務代碼現已開放使用。如要瞭解最新狀態，請參閱公告網誌文章。

我們在初期測試時，採用了「BYOS」模式。長期來說，廣告技術需要使用在受信任執行環境中執行的開源 Protected Audience API 鍵/值服務。

如要瞭解時間表的最新資訊，請參閱 Protected Audience API 服務部落格文章。我們會在轉換作業開始前，提前通知開發人員，讓他們開始測試及採用。

偵測功能支援

使用 API 前，請先確認瀏覽器是否支援該 API，以及該 API 是否可用於文件：

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Protected Audience API 如何運作？

在這個範例中，使用者瀏覽自訂自行車製造商的網站，之後造訪新聞網站時，會看到這家自行車製造商的新款自行車廣告。

隨著導入作業的進度，Protected Audience API 的功能也會隨之增加。

1. 使用者造訪廣告主網站

有人在筆記型電腦的瀏覽器中造訪自行車客製化製造商網站。

假設使用者造訪客製自行車製造商 (在本例中為廣告客戶) 的網站，並在手工鋼製自行車的產品頁面停留一段時間。這為單車製造商提供了再行銷機會。

2. 要求使用者的瀏覽器加入興趣群組

使用者在筆電上開啟瀏覽器並造訪網站。瀏覽器會執行加入廣告興趣群組的 JavaScript 程式碼。

廣告主的 DSP (或廣告主本身) 會呼叫 navigator.joinAdInterestGroup()，要求瀏覽器將興趣群組新增至瀏覽器所屬的群組清單。

在這個範例中，群組名稱為 custom-bikes，擁有者為 dsp.example。興趣群組擁有者 (在本例中為 DSP) 會成為 Protected Audience API 廣告競價中的買家。興趣群組成員資格會儲存在使用者裝置上的瀏覽器中，不會與瀏覽器供應商或其他人分享。

指定興趣群組的廣告

ads 和 adComponents 物件包含廣告素材的網址，以及可在出價時使用的任意中繼資料 (選用)。例如：

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

買家如何出價？

如果興趣群組的擁有者獲邀出價，系統會針對瀏覽器所屬的每個興趣群組呼叫 generateBid()。

參閱 generatedBid() 開發人員說明文件。

3. 使用者造訪販售廣告空間的網站

使用者在筆電的瀏覽器中造訪新聞網站。網站有空白廣告版位。

之後，使用者造訪販售廣告空間的網站，例如新聞網站。網站有廣告空間，可透過程式輔助即時出價進行銷售。

4. 在瀏覽器中執行廣告競價

使用者在筆電的瀏覽器中查看新聞網站。系統會執行 Protected Audience API 廣告競價，為可用的廣告空間挑選廣告。

廣告競價可能由發布商的供應方平台 (SSP) 或發布商自行執行。競價的目的，是為目前網頁上單一可用的廣告版位，選取最適合的廣告。競價會考量瀏覽器所屬的興趣群組，以及鍵/值服務的廣告空間買家和賣家資料。

5. 賣方和參與的買方向鍵/值服務要求即時資料

使用者在筆電的瀏覽器中查看新聞網站。正在進行使用 Protected Audience API 的廣告競價，參與者會從鍵/值服務取得資料。

在廣告競價期間，賣方可以向鍵/值服務提出要求，取得特定廣告素材的即時資料。賣家可以在runAdAuction() 期間透過 trustedScoringSignalsUrl 屬性要求這項資訊，以及競價中所有興趣群組的 ads 和 adComponents 欄位中所有項目的 renderUrl 屬性鍵。

買方可以使用傳遞至 navigator.joinAdInterestGroup() 的興趣群組引數的 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 屬性，向自己的 Key/Value 服務要求即時資料。

呼叫 runAdAuction() 時，瀏覽器會向每位廣告買家的受信任伺服器發出要求。要求的網址可能如下所示：

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • 基準網址來自 trustedBiddingSignalsUrl。
  • hostname 是由瀏覽器提供。
  • keys 值取自 trustedBiddingSignalsKeys。

這項要求的回應是 JSON 物件，可提供各個鍵的值。

6. 顯示得標廣告

使用者在筆電的瀏覽器中查看新聞網站。在安全區域框架中顯示單車 20% 折扣的廣告。

當拍賣設定中將 resolveToConfig 標記設為 true 時，runAdAuction() 傳回的承諾會解析為受限影格設定物件 (FencedFrameConfig)。柵欄式框架會使用框架設定，將框架導向勝出的廣告，但框架嵌入者看不到廣告的網址。

從 M114 開始，您可以使用區隔的邊界設定物件。如要進一步瞭解 FencedFrameConfig 物件，請參閱 Chrome 網誌文章。

7. 回報競價結果

我們的長期計畫是希望讓瀏覽器使用 Private Aggregation API，為賣家和買家回報競價結果。

由於這是臨時事件層級報表機制，因此為賣方實作 reportResult() 的程式碼，以及為得標出價者實作的 reportWin()，都可以呼叫 sendReportTo() 函式。這個方法會採用單一引數：代表競價完成後擷取的網址的字串，該網址會編碼要回報的事件層級資訊。

8. 回報廣告點擊

使用者在新聞網站上點按嵌入有圍框的自行車廣告。報表資料會傳送給賣方和買方。

系統會記錄在圍欄框架中顯示的廣告點擊次數。如要進一步瞭解這項功能的運作方式，請參閱「圍欄廣告報表」。

Protected Audience API 廣告競價的各個階段總覽
此圖表概略說明 Protected Audience API 競價的各個階段。

Protected Audience API 和 TURTLEDOVE 有何不同？

Protected Audience API 是 TURTLEDOVE 系列提案中，在 Chromium 中實作的首個實驗。

Protected Audience API 遵循 TURTLEDOVE 的高層原則。部分線上廣告會根據使用者先前與廣告客戶或廣告聯播網互動的情況，向可能感興趣的使用者顯示廣告。過去，廣告主會在使用者瀏覽各個網站時辨識特定使用者，這也是現今網路上最關鍵的隱私權問題。

TURTLEDOVE 計畫旨在提供新的 API 來處理此用途，同時提供一些重要的隱私權進展：

  • 瀏覽器會保留廣告主認為使用者感興趣的資訊，而非廣告主。
  • 廣告主可以根據興趣放送廣告，但不得將該興趣與使用者的其他資訊 (特別是使用者身分或造訪的網頁) 結合。

Protected Audience API 源自於 TURTLEDOVE 和一組相關的修訂提案，這些修訂提案可為使用 API 的開發人員提供更完善的服務：

  • 在 SPARROW 中：Criteo 建議新增在受信任的執行環境 (TEE) 中執行的服務模型 (「Gatekeeper」)。Protected Audience API 包含更受限的 TEE 用途，可用於即時資料查詢和匯總報表。
  • NextRoll 的 TERN 和 Magnite 的 PARRROT 提案說明瞭買方和賣方在裝置端競價中的不同角色。Protected Audience API 的廣告出價/評分流程就是以這項工作為基礎。
  • RTB House 的 以結果為準和 產品層級 TURTLEDOVE 修改內容，改善了裝置端競價的匿名模型和個人化功能
  • PARAKEET 是 Microsoft 提出的 TURTLEDOVE 類廣告服務提案，該服務會在瀏覽器和廣告技術供應商之間的 TEE 中執行 Proxy 伺服器，以匿名廣告請求和強制執行隱私權屬性。Protected Audience API 並未採用這種代理模式。我們正在將 PARAKEET 的 JavaScript API 和 Protected Audience API 對齊，以便在未來進一步結合兩項提案的最佳功能。

Protected Audience API 目前無法防止網站廣告聯播網瞭解使用者看到哪些廣告。我們預計會隨著時間的推移，修改 API 以提升隱私權。

Topics API 可與 Protected Audience API 搭配使用嗎？

可以。Topics API 提供的目前使用者觀察主題，可供賣家或出價方做為背景資訊使用。主題可納入下列屬性：

  • auctionSignals：傳遞至 navigator.runAdAuction() 的競價設定物件屬性
  • userBiddingSignals：傳遞至 navigator.joinAdInterestGroup() 的興趣群組設定物件屬性

可用的瀏覽器設定

使用者可以透過啟用或停用 chrome://settings/adPrivacy 中的頂層設定，調整在 Chrome 中參與 Privacy Sandbox 試驗的情況。

在初步測試期間，使用者可以使用這項高層級 Privacy Sandbox 設定，選擇停用 Protected Audience API。Chrome 計畫讓使用者查看及管理自己在造訪過的網站上加入的興趣群組清單。就像 Privacy Sandbox 技術本身一樣，使用者設定可能會隨著使用者、監管機構和其他人的意見回饋而有所調整。

我們會根據測試和意見回饋，持續更新 Chrome 中的可用設定。我們日後將提供更精細的設定，方便管理 Protected Audience API 和相關資料。

使用者在無痕模式下瀏覽網頁時，API 呼叫端無法存取群組會員資格，且會員資格會在使用者清除網站資料時移除。

瀏覽器是否會快取 Protected Audience 工作項？

瀏覽器會快取含有 Protected Audience 工作區塊的資源，包括買方出價產生和報表工作區塊，以及賣方廣告評分和報表工作區塊。您可以使用 Cache-Control 標頭控管快取行為。

互動及分享意見回饋

取得支援

如要提出問題並取得導入、示範或說明文件相關支援，請按照下列步驟操作：

如有其他一般問題，想瞭解如何透過 Protected Audience API 滿足需求，請在 API 存放區中提出問題。您也可以在 W3C 的 Improving Web Advertising Business Group 中討論業界用途。

使用 Privacy Sandbox 意見回饋表單，在公開論壇之外與 Chrome 團隊私下分享意見。

選擇停用

如要選擇不參與 Protected Audience API 測試，瞭解如何封鎖 Protected Audience API 的存取權，不論您是網站擁有者或個別使用者皆可使用這項功能。

取得最新消息