本頁面由 Cloud Translation API 翻譯而成。

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 部署作業造訪 protected-audience-demo.web.app/ 中的網站。

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

測試這個 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 金鑰/值服務代碼就能使用這項功能如要瞭解狀態更新，請參閱公告網誌文章。

如需初始測試，請使用「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。興趣群組擁有者 (在本例中為需求端平台) 將是買方參與的競價興趣群組成員資格是由瀏覽器儲存，不會與瀏覽器供應商或任何人分享。

閱讀 Protected Audience API 說明：瀏覽器記錄興趣群組。
閱讀 API 指南：買方和需求端平台，瞭解如何 joinAdInterestGroup()，然後產生出價。

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

注意：joinAdInterestGroup() 的呼叫結構定義來源必須與興趣群組擁有者的來源 joinAdInterestGroup() 必須透過興趣群組擁有者 (例如 DSP) 擁有的 iframe 呼叫。如果目前文件的來源與興趣群組擁有者相同 (例如擁有專屬興趣群組的網站)，則不必使用 iframe。

為興趣群組指定廣告

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

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

買方如何出價？

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

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

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

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

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

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

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

閱讀 Protected Audience API 說明：賣方執行裝置端競價
閱讀 API 指南：銷售人員可進一步瞭解相關資訊 runAdAuction()和廣告競價延遲最佳做法。

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 物件，為每一個鍵。

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

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

重點：在 Protected Audience API 的初始實驗階段時，「trustedBiddingSignalsUrl」的來源必須與興趣群組相同擁有者。詳情請參閱使用自己的伺服器。

6. 放送勝出的廣告

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

注意：只有在競價設定中將標記 resolveToConfig 設為 true 時，才會傳回 FencedFrameConfig 物件。如果未設定旗標，或為 false，系統會傳回不透明的 URN，但只能在 iframe 中顯示。

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

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

7. 系統回報競價結果

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

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

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

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

互動及分享意見回饋

取得支援

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

GitHub：閱讀釋疑影片提出問題並追蹤討論。
示範：提報範例程式碼存放區的問題。
開發人員支援：您可以提問或參與 Privacy Sandbox 開發人員支援。選取 Protected Audience API 的問題範本。
Chrome 實作：指出 Chrome 實作您可以透過 Protected Audience API，查看現有問題或提出新問題。

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

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

選擇停用

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

取得最新消息

如要收到 API 狀態變更的通知，請加入開發人員專用的郵寄清單。
如要密切追蹤 API 上所有進行中的討論，請點選 API 頁面上的「觀看」按鈕 GitHub。您必須有或建立 GitHub 帳戶。
如要取得 Privacy Sandbox 的整體最新消息，請訂閱 RSS 動態消息 [Privacy Sandbox 中的進度]。
加入已排定的 Protected Audience API 呼叫 (每第二週)。我們歡迎所有人加入- 請務必先加入 WICG。個人中心可以主動參與或單純聆聽！