Protected Audience API：開發人員指南

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

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

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

導入狀態

• Protected Audience API 提案現已正式發布。提出問題並追蹤討論。
• 待處理功能的 Protected Audience API 狀態詳細說明 Protected Audience API API 和功能的異動與改善項目。
• 閃爍狀態
• Protected Audience API Chrome 平台狀態：僅適用於 Chrome 中的 Protected Audience API。
• Ads API Chrome 平台狀態：一組可協助放送廣告的 API：Protected Audience API、Topics、Fenced Frames 和 Attribution Reporting。

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

Protected Audience API 簡介

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

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

試用 Protected Audience API

可用的 API 參考資料

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

• joinAdInterestGroup() 和 generateBid() 的買家指南。
• Protected Audience API 賣家指南 runAdAuction()
• 買家指南：reportWin() 和賣家指南：reportResult()
• Protected Audience API 疑難排解

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

Protected Audience API 範例

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

測試這個 API

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

• 啟用 chrome://settings/adPrivacy 下方的所有廣告隱私權 API。
• 透過指令列設定標記。如需 Protected Audience API 可用旗標的完整清單，請前往 Chromium Code Search。

在 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 或發布商) 的裝置端廣告選擇程序：根據競價出價和買方提供的中繼資料。
• 在暫時放寬的圍欄頁框中顯示廣告：允許廣告算繪使用網路存取權和記錄功能。

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

興趣群組權限

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

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

鍵/值服務

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

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

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

在初期測試階段，我們引入了「Bring Your Own Server」模式。長期來說，廣告技術需要使用在受信任執行環境中執行的開源 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. 要求使用者的瀏覽器加入興趣群組

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

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

• 閱讀 Protected Audience API 說明：瀏覽器記錄興趣群組。
• 閱讀 API 指南：買方和 DSP，瞭解如何joinAdInterestGroup()並產生出價。

指定興趣群組的廣告

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

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

買家如何出價？

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

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

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

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

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

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

• 閱讀 Protected Audience API 說明：賣方執行裝置端競價
• 閱讀 API 指南：賣家可以進一步瞭解 runAdAuction() 和廣告競價延遲最佳做法。

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

在廣告競價期間，賣方可以向鍵/值服務提出要求，取得特定廣告素材的即時資料。賣家可以在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 物件，可提供各個鍵的值。

• 閱讀 Protected Audience API 說明：從 Protected Audience API 鍵/值服務擷取即時資料。
• 請參閱公開提供 Protected Audience API 鍵/值服務。

6. 顯示得標廣告

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

從 M114 開始，您可以使用柵欄式影格設定物件。如要進一步瞭解 FencedFrameConfig 物件，請參閱 Chrome 網誌文章。

• 閱讀 Protected Audience API 說明：瀏覽器會轉譯獲勝廣告

7. 回報競價結果

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

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

• 閱讀 API 指南：瞭解賣家和買家報表

8. 回報廣告點擊

系統會回報在封閉式框架中顯示的廣告點擊次數。如要進一步瞭解這項功能的運作方式，請參閱「Fenced Frames Ads Reporting」。

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，讓 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 標頭來控制快取行為。

互動並分享意見回饋

取得支援

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

• GitHub：閱讀說明文章、提出問題並參與討論。
• 示範：在示範程式碼存放區中提出問題。
• 開發人員支援：在 Privacy Sandbox 開發人員支援專案中提問及參與討論。選取 Protected Audience API 的問題範本。
• Chrome 導入：如果 Chrome 導入 Protected Audience API 時發生錯誤或問題，您可以查看現有問題或提出新問題。

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

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

選擇停用

想停用 Protected Audience API 嗎？瞭解如何封鎖 Protected Audience API 的存取權，不論您是網站擁有者或個別使用者皆可使用這項功能。

取得最新消息

• 如要接收 API 狀態變更通知，請加入開發人員郵寄清單。
• 如要密切追蹤所有正在進行的 API 討論，請按一下 GitHub API 頁面的「Watch」按鈕。您必須建立 GitHub 帳戶，才能使用這項功能。
• 如要取得 Privacy Sandbox 的整體最新消息，請訂閱 RSS 動態消息 [Progress in the Privacy Sandbox]。
• 加入 Protected Audience API 的預約通話 (每兩週一次)。歡迎所有人加入。如要參與，請務必先加入 WICG。您可以主動參與，也可以只是旁聽！