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 示範

您可以在 Protect-audience-demo.web.app/ 瞭解廣告客戶和發布商網站的基本 Protected Audience API 部署作業。

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

使用 chrome://flags 或功能旗標進行測試

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

在 iframe 或 Fenced 頁框中顯示廣告

視已設定的標記而定，廣告可以在 <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 的下列功能：

  • 興趣群組：由瀏覽器儲存，其中包含設定廣告出價和算繪作業的相關中繼資料。
  • 買方 (需求端平台或廣告主) 的裝置端出價：依據已儲存的興趣群組和賣方的信號。
  • 賣方 (賣方平台或發布商) 的裝置端廣告選擇：根據買方的競價出價和中繼資料。
  • 在 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. 使用者的瀏覽器會要求新增興趣群組

使用者在筆電上開啟瀏覽器並造訪網站。瀏覽器正在執行用來加入廣告興趣群組的 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 屬性，從鍵/值服務要求即時資料。

瀏覽器呼叫 runAdAuction() 時，瀏覽器會向每個廣告買家的信任伺服器發出請求。該要求的網址看起來會像這樣：

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

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

6. 放送勝出的廣告

一個人在筆電上使用瀏覽器瀏覽新聞網站。一則在安全的圍欄頁框中顯示腳踏車 8 折促銷的廣告。

當競價設定的 resolveToConfig 標記設為 true 時，runAdAuction() 傳回的承諾會解析為圍欄頁框設定物件 (FencedFrameConfig)。圍欄頁框使用頁框設定來瀏覽勝出的廣告，但頁框嵌入程式看不到廣告網址。

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

7. 系統記錄競價結果

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

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

8. 系統記錄一次廣告點擊

一名使用者按下新聞網站上設有圍欄的單車廣告。系統會將報表資料傳送給賣方和買方。

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

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) 中執行的 (「總機」) 服務模型。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 的頂層設定，藉此調整是否參與 Chrome 的 Privacy Sandbox 試用計畫。

在初始測試期間，使用者可以使用這項高階 Privacy Sandbox 設定，選擇不採用 Protected Audience API。Chrome 打算讓使用者在造訪過的網站中，查看及管理興趣群組清單。就像 Privacy Sandbox 技術本身，使用者設定可能會隨著使用者、監管機構等的意見回饋而調整。

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

使用者在無痕模式下瀏覽網頁時，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 存取權。

取得最新消息