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 是在 Chromium 的 TURTLEDOVE 提案系列中實作的第一個實驗。

試用 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 部署作業，請前往 Protect-audience-demo.web.app/。

測試這個 API

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

• 啟用 chrome://settings/adPrivacy 下的所有廣告隱私權 API。
• 透過指令列設定標記。如需可用的 Protected Audience API 標記完整清單，請參閱 Chromium 程式碼搜尋。

在 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 功能的實驗：

• 興趣群組：由瀏覽器儲存，以及相關中繼資料，用來設定廣告出價和顯示方式。
• 買方的裝置端出價 (DSP 或廣告客戶)：根據已儲存的興趣群組和賣方提供的信號。
• 賣方 (賣方平台或發布商) 選擇裝置端廣告：根據買方出價和中繼資料。
• 在暫時寬鬆的 Fenced Frames 中顯示廣告：允許存取網路及記錄廣告。

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

興趣群組權限

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

日後，一旦網站擁有者有時間更新跨網域 iframe 權限政策後，計畫就會禁止來自跨網域 iframe 的呼叫。

鍵/值服務

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

• 買方可能會想計算廣告活動的剩餘預算。
• 賣方可能需要根據發布商政策檢查廣告素材。

Protected Audience API 金鑰/值服務程式碼現已推出。如要瞭解狀態更新，請參閱公告網誌文章。

在初始測試中，我們推出了「自備伺服器」模型。長期來看，廣告技術人員需要使用開放原始碼 Protected Audience API 鍵/值服務，在受信任的執行環境中運作。

如需時間軸更新相關資訊，請參閱 Protected Audience 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 指南：買方和需求端平台，瞭解如何 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 屬性，從鍵/值服務要求即時資料。

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

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

• 基準網址來自 trustedBiddingSignalsUrl。
• hostname 是由瀏覽器提供。
• keys 值取自 trustedBiddingSignalsKeys。

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

• 閱讀 Protected Audience API 說明：從 Protected Audience API 金鑰/值服務擷取即時資料。
• 請參閱「Open sourcing the Protected Audience API Key/Value 服務」。

6. 放送勝出的廣告

競價設定中，resolveToConfig 標記設為 true 時，runAdAuction() 傳回的承諾會解析為圍欄頁框設定物件 (FencedFrameConfig)。Fenced Frame 會使用頁框設定，將頁框帶往勝出的廣告，但頁框嵌入器不會顯示廣告網址。

Fenced Frame 設定物件自 M114 起開始提供。如要進一步瞭解 FencedFrameConfig 物件，請參閱 Chrome 網誌文章。

• 閱讀 Protected Audience API 說明：瀏覽器顯示勝出的廣告

7. 系統回報競價結果

我們的長期計畫是允許瀏覽器使用 Private Aggregation API 回報賣方和買方的競價結果。

做為暫時性的事件層級回報機制，為賣方實作 reportResult() 的程式碼，以及為得標出價方實作 reportWin() 的程式碼，可以呼叫 sendReportTo() 函式。這會使用單一引數：代表在競價完成後擷取的網址字串，該字串會將要回報的事件層級資訊編碼。

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

8. 回報一次廣告點擊

系統會回報在圍欄頁框中顯示的廣告點擊次數。如要進一步瞭解相關運作方式，請參閱「Fenced Frames 廣告報表」。

---

Protected Audience API 與 TURTLEDOVE 有何不同？

Protected Audience API 是第一個在 Chromium 中導入 TrifOVE 提案系列的實驗。

Protected Audience API 遵循 TURTLEDOVE 的概略原則。有些線上廣告是根據之前曾與廣告客戶或廣告聯播網互動的潛在興趣使用者顯示廣告。以往，廣告主可在瀏覽網站時辨識特定使用者，這也是現今網路隱私權的核心考量。

TURTLEDOVE 主要是提供新 API 來因應這個使用情境，同時提供了一些重要的隱私權保護：

• 瀏覽器 (而非廣告客戶) 具有廣告客戶認為使用者感興趣的相關資訊。
• 廣告主可以根據興趣放送廣告，但無法將興趣及其他相關資訊結合，尤其是目標對象的身分或正在造訪的頁面。

Protected Audience API 是從 TURTLEDOVE 成長而來，同時也是一系列的修改相關提案，為使用 API 的開發人員提供更完善的服務：

• 在 SPARROW 中：Criteo 提議新增在信任的執行環境 (TEE) 中執行的 (「總機人員」) 服務模型。Protected Audience API 包含更有限的 TEE 用途，可用於即時資料查詢和匯總報表。
• NextRoll 的 TERN 和 Magnite 的 PARRROT 提案說明瞭買方和賣方在裝置端競價中扮演的不同角色。Protected Audience API 的廣告出價/評分流程是以這項工作為基礎。
• RTB House 的依據結果和產品層級經過 TURTLEDOVE 修改，改善裝置端競價的匿名模型和個人化功能
• PARAKEET 是 Microsoft 針對類似 TURTLEDOVE 的廣告服務提出的提案，這類服務仰賴在瀏覽器和廣告技術供應商之間在 TEE 中執行的 Proxy 伺服器，以便將廣告請求去識別化，並強制執行隱私權屬性。Protected Audience API 尚未採用這個 Proxy 模型。我們將調整 PARAKEET 和 Protected Audience API 的 JavaScript 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 呼叫端無法存取群組成員，而使用者清除網站資料後，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。您可以積極參與，也可以單純聆聽！