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 和功能的變更和強化。
• 閃爍狀態
• Protected Audience API Chrome 平台狀態：適用於 Chrome 上的 Protected Audience API。
• 廣告 API Chrome 平台狀態：一系列有助於廣告的 API，包括 Protected Audience API、Topics、Fenced Frames 和 Attribution Reporting。

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

什麼是 Protected Audience API？

Protected Audience API 是一種 Privacy Sandbox API，專為提供再行銷和自訂目標對象用途而設計，第三方無法使用這項 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，請前往 protected-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，以及該 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 屬性，向鍵/值服務要求即時資料。

叫用 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() 傳回的 Promise 會解析為設有安全範圍的影格設定物件 (FencedFrameConfig)。受限框架會使用框架設定，將框架導向勝出廣告，但廣告網址不會顯示給框架嵌入者。

M114 以上版本提供設有圍欄的影格設定物件。如要進一步瞭解 FencedFrameConfig 物件，請參閱 Chrome 網誌文章。

• 閱讀 Protected Audience API 說明文件：瀏覽器會算繪勝出的廣告

7. 系統會回報競價結果

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

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

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

8. 系統回報廣告點擊

系統會回報在設有圍欄的影格中顯示的廣告點擊次數。如要進一步瞭解這項功能，請參閱「受限框架廣告報表」。

Protected Audience API 和 TURTLEDOVE 有何不同？

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

Protected Audience API 遵循 TURTLEDOVE 的高階原則。部分線上廣告會向先前與廣告主或廣告聯播網互動的使用者顯示廣告，因為他們可能對廣告內容感興趣。過去，廣告主會辨識出在網站間瀏覽的特定使用者，藉此放送廣告，但這也是現今網路上的一大隱私權問題。

TURTLEDOVE 計畫旨在提供新的 API 來解決這個用途，同時在隱私權方面取得重大進展：

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

Protected Audience API 源自 TURTLEDOVE，以及一系列相關提案，旨在修改 API，以便更妥善地服務使用 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 中啟用或停用 chrome://settings/adPrivacy 的頂層設定，調整是否參與 Privacy Sandbox 試用。

在初步測試期間，使用者可以透過這個高階 Privacy Sandbox 設定停用 Protected Audience API。Chrome 預計會讓使用者查看及管理自己加入的興趣群組清單，這些群組來自使用者造訪的網站。與 Privacy Sandbox 技術本身一樣，使用者設定可能會根據使用者、監管機構和其他各方的意見回饋而有所變更。

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

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

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

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

參與討論及分享意見

取得支援

如要提出問題，並取得導入、試用或文件方面的支援，請按照下列步驟操作：

• GitHub：請參閱說明、提出問題，並追蹤討論內容。
• 試用：在試用程式碼存放區提出問題。
• Chrome 導入做法：如要回報 Chrome 導入 Protected Audience API 時發生的錯誤或問題，可以查看現有問題或提出新問題。

如對如何使用 Protected Audience API 滿足需求有一般問題，請在 API 存放區中提出問題。您也可以在 W3C 的改善網路廣告業務群組中，討論產業用途。

使用 Privacy Sandbox 意見回饋表單，在公開論壇以外的管道，私下向 Chrome 團隊提供意見。

選擇停用

如要停用 Protected Audience API，瞭解如何封鎖 Protected Audience API 的存取權 (網站擁有者或個人使用者)。

取得最新消息

• 如要接收 API 狀態異動通知，請加入開發人員郵寄清單。
• 如要密切追蹤 API 的所有討論內容，請按一下 GitHub 上 API 頁面的「Watch」按鈕。您必須擁有或建立 GitHub 帳戶。
• 如要掌握 Privacy Sandbox 的整體最新動態，請訂閱 RSS 摘要 [Privacy Sandbox 進展]。
• 加入 Protected Audience API 的預定通話 (每隔一週)。歡迎所有人加入，如要參與，請務必先加入 WICG。你可以主動參與或只是聆聽！