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

試用 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 的部分功能：

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

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

興趣群組權限

根據目前預設的 Protected Audience API 實作方式，系統將允許呼叫 joinAdInterestGroup()敬上 從網頁中的任何位置，即使是跨網域 iframe 也行

日後網站擁有者有空更新跨網域 iframe 權限政策、 計劃禁止來自跨網域 iframe 的呼叫。

鍵/值服務

為了支援 Protected Audience API 廣告競價，瀏覽器可以存取 鍵/值服務 擷取即時資訊，支援 Protected Audience API 廣告競價。這個 這份報告的應用方式包括：

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

Protected Audience API 金鑰/值服務代碼 就能使用這項功能如要瞭解狀態更新，請參閱公告網誌文章。

如需初始測試，請使用「Bring Your Own Server」(自備伺服器) 最終介紹過的模型長期來看，廣告技術人員需要使用 開放原始碼 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 在瀏覽器中執行加入廣告群組程式碼的程式碼。

廣告客戶的需求端平台 (或廣告客戶本身) 呼叫 navigator.joinAdInterestGroup()：要求瀏覽器新增興趣群組 附加至瀏覽器所屬的群組清單

在這個範例中，群組的名稱為 custom-bikes，擁有者為 dsp.example。興趣群組擁有者 (在本例中為需求端平台) 將是買方 參與的競價興趣群組成員資格是由瀏覽器儲存， 不會與瀏覽器供應商或任何人分享。

，瞭解如何調查及移除這項存取權。

為興趣群組指定廣告

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

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

買方如何出價？

系統會針對瀏覽器所屬的每個興趣群組呼叫 generateBid() 。

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

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

一個人使用筆電的瀏覽器造訪新聞網站。網站 擁有空白的廣告版位。

之後，使用者造訪銷售廣告空間的網站，在本例中為 網站。該網站提供廣告空間，並以程式輔助方式販售 即時出價

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

一個人使用筆電的瀏覽器瀏覽新聞網站。執行 Protected Audience API 廣告競價，為可用的廣告空間挑選廣告。

廣告競價可能會由發布商的供應端供應商執行 (賣方平台) 或發布商本身。競價的目的是 在目前網頁的某一個可用廣告版位中選出最適當的廣告。 競價時會考量瀏覽器所屬的興趣群組 以及來自廣告空間買方和 鍵/值服務：

5. 賣方和參與買方要求「鍵/值」服務提供即時資料

使用者透過筆電的瀏覽器查看新聞網站。廣告 競價開始，參與者會從鍵/值服務取得資料。

在廣告競價期間，賣方可請求特定廣告的即時資料 方法是向其鍵/值服務提出要求。 賣方可在 runAdAuction() (來自 trustedScoringSignalsUrl 屬性)， 以及 ads 中所有項目的 renderUrl 屬性鍵 和競價中所有興趣群組的 adComponents 欄位。

買方可以使用 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 屬性 傳遞至 navigator.joinAdInterestGroup() 的興趣群組引數。

當呼叫 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 會使用頁框設定，將頁框帶往勝出的廣告，但頁框嵌入器不會顯示廣告網址。

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

7. 系統回報競價結果

我們的長期計劃是讓瀏覽器記錄 賣方和買方使用私密匯總 API

做為暫時性的事件層級回報機制，將導入程式碼 reportResult()對賣方和reportWin()得標者來說， 呼叫 sendReportTo() 函式。這需要使用單一引數：字串 代表競價完成後擷取的網址， 需要回報的事件層級資訊

8. 回報一次廣告點擊

一名使用者在新聞網站上點選了內嵌於圍欄框架的單車廣告。報表資料會傳送給賣方和買方。

系統會回報在圍欄頁框中顯示的廣告點擊次數。如要進一步瞭解 可能的運作情形，請參閱圍欄頁框廣告報表。

Protected Audience API 廣告競價各階段的總覽
此圖表列出 Protected Audience API 競價的各個階段。

Protected Audience API 與 TURTLEDOVE 有何不同？

Protected Audience API 是第一個在 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 針對仰賴 Proxy 的 TURTLEDOVE 廣告服務提案 伺服器與廣告技術供應商之間在 TEE 中執行。 以匿名方式傳送廣告請求，並保障隱私權 資源。Protected Audience API 尚未採用這個 Proxy 模型。這次我們隆重推出 將 PARAKEET 和 Protected Audience API 的 JavaScript API 和 Protected Audience API 對齊，以支援 日後將進一步整合這兩種提案的優點

Protected Audience API 尚未防止網站廣告聯播網得知使用者會看到哪些廣告。我們期望能隨著時間修改 API，提高隱私性。

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

可以。針對目前使用者觀察到的主題 (由 Topics API 提供) 可用來做為 賣方或出價工具的內容比對資訊主題 並列出以下屬性：

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

可用的瀏覽器設定

使用者可以透過下列方式調整自己參與 Chrome 的 Privacy Sandbox 試用計畫： 啟用或停用頂層設定： chrome://settings/adPrivacy。

在初始測試期間，使用者將可使用這項 用來停用 Protected Audience API 的沙箱設定。Chrome 計劃讓使用者 管理網路上新增的興趣群組清單 。和 Privacy Sandbox 技術本身一樣 根據使用者、監管機構等機構的意見回饋，改善使用者設定。

我們會持續根據測試和意見回饋，持續更新 Chrome 的可用設定。 日後，我們預計提供更多精細的設定，以便管理 Protected Audience API，以及 關聯資料

當使用者以無痕模式瀏覽網頁時，API 呼叫端無法存取群組成員。 和使用者清除網站資料後，成員資格就會遭到移除。

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

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

互動及分享意見回饋

取得支援

如需導入作業、示範或 說明文件：

如有關於使用 Protected Audience API 需求的一般問題， 在 API 存放區中回報問題。 您也可以前往 W3C 的 改善網路廣告企業集團。

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

選擇停用

要選擇退出 Protected Audience API 嗎？瞭解詳情 禁止存取 Protected Audience API， 做為網站擁有者或個別使用者

取得最新消息