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

FLEDGE API 開發人員指南

這篇文章的適用對象為何？

本文提供目前實驗性 Protected Audience API 疊代的技術參考資料。

Protected Audience API 是提案的技術總覽，且還有詞彙表
Protected Audience 示範提供基本 FLEDGE 的逐步操作說明可能面臨擴充性、監控、持續整合和部署等方面的挑戰
Protected Audience 示範影片說明程式碼範例的運作方式，以及如何使用 Chrome 開發人員工具進行 Protected Audience 偵錯。

什麼是 Protected Audience？

Protected Audience API 是一項 Privacy Sandbox 提案再行銷和自訂目標對像用途，因此在設計上無法來追蹤使用者在各網站上的瀏覽行為。API 啟用裝置端競價時瀏覽器並選擇相關廣告。

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

下圖概略說明 FLEDGE 生命週期：

如何試用 Protected Audience？

Protected Audience 示範

您可以前往下列網址，瞭解廣告客戶和發布商網站如何部署 Protected Audience 的基本部署作業： protected-audience-demo.web.app.

示範影片說明程式碼範例的運作方式，以及如何使用 Chrome 開發人員工具進行 Protected Audience 偵錯。

參與 Protected Audience 來源試用

Privacy Sandbox 關聯性和評估來源試用已經結束適用於 Protected Audience 的桌機 Chrome Beta 版 101.0.4951.26 以上版本，主題，以及 Attribution Reporting API。

如要參與測試，請註冊來源試用權杖。

成功註冊試用方案後，即可在網頁上試用 Protected Audience JavaScript API 提供有效的試用權杖，例如要求瀏覽器加入一或多個興趣群組；並進行廣告競價，選出並顯示廣告。

Protected Audience 示範提供端對端 Protected Audience 部署的基本範例。

針對要執行 Protected Audience API 程式碼的每個網頁，提供試用權杖：

做為 <head>:
的中繼標記

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
做為 HTTP 標頭：

Origin-Trial: TOKEN_GOES_HERE

透過程式輔助方式提供權杖：

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

執行 Protected Audience 程式碼的 iframe，例如 navigator.joinAdInterestGroup() 興趣群組擁有者呼叫) 必須提供與來源相符的符記。

提議的第一個 Protected Audience 來源試用詳細資料進一步說明第一次試用的目標及支援的功能。

測試這個 API

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

啟用 chrome://settings/adPrivacy 下的所有廣告隱私權 API
從指令列設定旗標。

在 iframe 或圍欄頁框中顯示廣告

廣告可在 <iframe> 或 <fencedframe> 中顯示，取決於設定的旗標

若要使用「<fencedframe>」顯示廣告，請按照下列步驟操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

若要使用「<iframe>」顯示廣告，請按照下列步驟操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

加入 BiddingAndScoringDebugReportingAPI 標記，啟用暫時偵錯損失/勝出報表方法。

執行含旗標的 Chromium 說明如何在執行 Chrome 和其他以 Chromium 為基礎的瀏覽器時，透過互動如需 Protected Audience 標記的完整清單，請前往 Chromium 程式碼搜尋工具。

最新版本的 Chrome 支援哪些功能？

目前 Chromium 的功能旗標背後即支援 Protected Audience 實驗，測試以下 Protected Audience 提案的下列功能：

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

API 說明頁面瞭解功能支援和限制

興趣群組權限

目前的 Protected Audience 預設設定是允許從以下位置呼叫 joinAdInterestGroup()：網頁中的任何位置，即使是跨網域 iframe 也行。一旦網站擁有者有時間調整跨網域 iframe 權限政策，計畫禁止來自跨網域 iframe

鍵/值服務

參與 Protected Audience 廣告競價時，瀏覽器可以存取鍵/值服務會傳回簡單的鍵/值組合，將資訊提供給廣告買方，例如：廣告活動預算Protected Audience 提案授權書此伺服器「不會執行任何事件層級記錄」，並且沒有根據這些要求」。

Privacy Sandbox GitHub 存放區現已提供 Protected Audience 鍵/值服務程式碼。Chrome 和 Android 開發人員可使用這項服務。如要瞭解狀態更新，請參閱公告網誌文章。如要進一步瞭解 Protected Audience 鍵/值服務，請參閱 API 說明和信任模型說明。

初始測試會使用「自備伺服器」模式。長期來看，廣告技術人員將需要使用開放原始碼 Protected Audience 鍵/值服務，在受信任的執行環境中運作，才能擷取即時資料。

為了確保生態系統有足夠時間進行測試，我們預計在第三方 Cookie 淘汰後一段時間，才要求使用開放原始碼鍵/值服務或 TEE。我們會在轉換開始之前，提供重大通知，讓開發人員開始測試和採用。

偵測功能支援

使用 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？

您可以禁止網站擁有者或個別使用者的身分存取 Protected Audience API。

網站如何控管存取權？

Protected Audience 最終會要求網站設定權限政策才能提供 Protected Audience 功能這樣一來，如果未有網站相關知識不過，為了在首次來源試用期間進行測試，這項規定預設為免除。如要在測試期間明確停用 Protected Audience 功能，可以使用相關的權限政策來封鎖存取權

以下兩項可獨立設定 Protected Audience 權限政策：

join-ad-interest-group 會啟用/停用將瀏覽器加入興趣群組的功能
run-ad-auction 會啟用/停用在裝置端競價的功能

您可在第一方情境中指定下列，完全停用 Protected Audience API 存取權。將權限政策納入 HTTP 回應標頭：

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

如要停用 iframe 中的 API，請將下列 allow 屬性新增至 iframe 元素：

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

詳情請參閱「提議的第一個 Protected Audience 來源試用權限政策」一節。

讓使用者選擇不接受

使用者可以透過以下任一種方式，封鎖 Protected Audience API 和其他 Privacy Sandbox 功能的存取權：以下機制：

在 Chrome 設定中停用 Privacy Sandbox 試用期：依序點選「設定」> 安全性與隱私權 >Privacy Sandbox。你也可以前往 chrome://settings/adPrivacy 存取這項資訊。
在 Chrome 設定中停用第三方 Cookie：[設定] >安全性與隱私權：
將「Cookie 和其他網站資料」設為「封鎖第三方 Cookie」或「封鎖所有 Cookie」出發地：chrome://settings/cookies。
使用無痕模式。

Protected Audience 說明內容會進一步說明 API 設計元素，並說明 API 尋求如何達成隱私權目標。

偵錯 Protected Audience 功能

在 Chrome Canary 98.0.4718.0 中，您可以使用 Chrome 開發人員工具中的 Protected Audience 功能偵錯。

第一步是透過「事件監聽器中斷點」窗格中的新類別設定中斷點「來源」面板中。

螢幕截圖
Chrome Canary 中的開發人員工具，醒目顯示「來源」面板中的「事件監聽器中斷點」窗格。
已選取「廣告競價小程式」下方的「出價方出價階段開始」。

中斷點觸發時，系統會在 Worklet 指令碼您可以使用一般中斷點或步驟指令取得出價/評分/報表函式本身

即時 Worklet 指令碼也會顯示在「Threads」面板下方。

螢幕截圖
Chrome Canary 中的開發人員工具，醒目顯示「來源」面板中的「Threads」窗格，顯示目前的
工作程式指令碼已遭暫停

由於某些工作程式可能會同時執行，因此多個執行緒最終可能會在「暫停」狀態出現。。您可以使用執行緒清單來切換執行緒，並繼續或更密切地檢查執行緒或適當。

觀察 Protected Audience 事件

在 Chrome 開發人員工具的「應用程式」面板中，您可以觀察 Protected Audience 興趣群組和競價事件。

如果您造訪 Protected Audience 示範購物網站如果瀏覽器已啟用 Protected Audience，開發人員工具就會顯示 join 事件的相關資訊。

Chrome Canary 中的開發人員工具應用程式面板，顯示 Protected Audience 興趣群組相關資訊
加入活動。

現在，如果您造訪 Protected Audience 示範發布商網站如果是已啟用 Protected Audience 的瀏覽器，開發人員工具會顯示 bid 和 win 事件的相關資訊。

Chrome Canary 中的開發人員工具應用程式面板，顯示 Protected Audience 競價出價和
贏得事件

Protected Audience API 的運作方式為何？

在本例中，使用者瀏覽客製化單車製造商的網站，然後造訪新聞網站顯示單車製造商推出新單車的廣告

1. 使用者造訪廣告主的網站

假設某位使用者造訪了客製化單車製造商的網站 (廣告客戶並花了一些時間在產品頁面上購買手工鋼鐵腳踏車。這樣就能且具備再行銷機會的自行車製造商。

2. 使用者的瀏覽器被要求新增興趣群組

插圖：使用者正在使用筆電的瀏覽器查看網站。JavaScript
code JoinAdInterestGroup() 在瀏覽器中運作。

說明部分： 瀏覽器記錄感興趣的群組

廣告客戶的需求端平台 (DSP) (或廣告客戶) 本身) 呼叫 navigator.joinAdInterestGroup()，要求瀏覽器將興趣群組加入瀏覽器所屬的群組清單。在這個範例中，群組名稱為 custom-bikes。擁有者為 dsp.example。興趣群組擁有者 (在本例中為需求端平台) 將會是買方 (如步驟 4 所述)。興趣群組成員資格是由瀏覽器儲存在使用者的裝置上，不會與或瀏覽器供應商或其他人員

注意：joinAdInterestGroup() 的呼叫情境來源必須與興趣群組相符因為必須從 iframe 呼叫 joinAdInterestGroup() 例如來自 DSP) 的資料，除非興趣群組擁有者的來源與目前來源的文件 (例如有專屬興趣群組的網站)。 runAdAuction 沒有相同的要求，因此從runAdAuction() <script>代碼的成效可能遠高於跨來源 iframe。

「joinAdInterestGroup()」需要下列權限：

造訪的網站
興趣群組擁有者

舉例來說，malicious.example 不得呼叫 joinAdInterestGroup()，在未經以下許可的情況下擔任擁有者：dsp.example dsp.example。

來自所造訪網站的權限

相同來源：根據預設，系統會隱含從以下來源發出的 joinAdInterestGroup() 呼叫授予權限與訪客造訪的網站來源相同，亦即來自與網站頂層頁框相同的來源目前的頁面。網站可以使用 Protected Audience 權限政策標頭用於停用 joinAdInterestGroup() 呼叫的 join-ad-interest-group 指令。

跨來源：從與目前以外的來源呼叫 joinAdInterestGroup() 網頁必須設定允許呼叫 joinAdInterestGroup() 來自跨來源 iframe。

注意：目前採用 Protected Audience 目前的預設設定是允許呼叫 joinAdInterestGroup() 也能從網頁中任何位置甚至是跨來源 iframe將來調整權限政策，則根據預設，此計畫預設為禁止透過跨來源 iframe。

來自興趣群組擁有者的權限

呼叫 joinAdInterestGroup() 會間接授予興趣群組擁有者權限來自與興趣群組擁有者相同的 iframe。例如 dsp.example iframe 可以為 dsp.example 擁有的興趣群組呼叫 joinAdInterestGroup()。

提案允許 joinAdInterestGroup() 在擁有者網域的網頁或 iframe 中執行，或使用 .well-known 網址的清單，委派給其他網域。

使用 navigator.joinAdInterestGroup()

以下是 API 的使用範例：

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

傳遞至函式的 interestGroup 物件大小不得超過 50 KB，否則為呼叫。第二個參數指定興趣群組的時間長度 (上限為 30 個) 天。連續呼叫會覆寫先前儲存的值。

重點：所有用來做為 Protected Audience API 方法參數的網址，都必須來自安全來源：所有資源都必須透過 HTTPS 網址提供如何利用 HTTPS 進行本機開發說明瞭如何在本機執行 Protected Audience 時進行這項操作。此外，biddingLogicUrl、decisionLogicUrl 和 trustedBiddingSignals 都需要使用 X-Allow-FLEDGE: true HTTP 回應標頭。

興趣群組屬性

屬性	必填	範例	角色
`owner`	必填	`'https://dsp.example'`	興趣群組擁有者的來源。
`name`	必填	`'custom-bikes'`	興趣群組名稱。
`biddingLogicUrl`**	選填*	`'https://dsp.example/bid/custom-bikes/bid.js'`	在 Worklet 中執行的出價 JavaScript 出價。
`biddingWasmHelperUrl`**	選填*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	由 `biddingLogicUrl` 驅動的 WebAssembly 程式碼的網址。
`dailyUpdateUrl`**	選用	`'https://dsp.example/bid/custom-bikes/update'`	傳回 JSON 以更新興趣群組屬性的網址。 (請參閱「更新興趣群組」)。
`trustedBiddingSignalsUrl`**	選用	`'https://dsp.example/trusted/bidding-signals'`	向出價工具受信任伺服器發出的鍵/值請求基準網址。
`trustedBiddingSignalsKeys`	選用	`['key1', 'key2' ...]`	向鍵/值受信任伺服器發出的要求的鍵。
`userBiddingSignals`	選用	`{...}`	擁有者可在出價時使用的其他中繼資料。
`ads`	選填*	`[bikeAd1, bikeAd2, bikeAd3]`	系統可能會向這個興趣群組放送的廣告。
`adComponents`	選用	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	由多個部分構成的廣告元件。

* 除了 owner 和 name 以外，所有屬性均為選用屬性。《biddingLogicUrl》和《ads》屬性為選用，但如果要參與競價，則為必要屬性。您可能適合用在建立不含這些屬性的興趣群組：舉例來說，興趣群組擁有者可能會您想針對尚未放送的廣告活動，在興趣群組中加入瀏覽器或廣告預算可能暫時用盡。

** biddingLogicUrl、biddingWasmHelperUrl、dailyUpdateUrl 和 trustedBiddingSignalsUrl 網址的來源必須與擁有者相同。ads 和 adComponents 網址則沒有這類限制。

更新興趣群組屬性

dailyUpdateUrl 會指定傳回 JSON 定義興趣群組屬性的網路伺服器。對應至傳送至 navigator.joinAdInterestGroup() 的興趣群組物件。這個為群組的擁有者提供一種機制，定期更新興趣群組在目前的實作方式中以下為可變更的屬性：

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

任何未在 JSON 中指定的欄位都不會覆寫，只有 JSON get 中指定的欄位才會覆寫已更新—但呼叫 navigator.joinAdInterestGroup() 會覆寫任何現有的興趣群組。

系統會盡可能進行更新，在下列情況中可能會失敗：

網路要求逾時 (目前為 30 秒)。
其他網路故障。
JSON 剖析失敗。

如果花費太多連續時間進行更新，也可以取消更新，但這並非對於已取消 (其餘) 的更新，這項操作並未強制規定任何頻率限制。更新的頻率限制在每天最多一次如果更新作業因網路錯誤而失敗，系統會在一小時後重試；如果更新作業因網際網路連線中斷而失敗，會在重新連線時立即重試。

手動更新

你可以透過以下方式，手動觸發當前頁框來源擁有的興趣群組更新： navigator.updateAdInterestGroups()。頻率限制可避免更新頻率過高：重複呼叫 navigator.updateAdInterestGroups() 在頻率限制之前不會執行任何動作週期 (目前為一天) 已過。如果發生下列情況，系統會重設頻率限制系統針對同一個興趣群組 owner 和 name，再次呼叫 navigator.joinAdInterestGroup()。

自動更新

競價完成後，所有為競價載入的興趣群組都會自動更新。且遵循的頻率限制與手動更新相同。為至少擁有一個興趣群組的每位擁有者參與競價則指 navigator.updateAdInterestGroups() 被呼叫來源與該擁有者相符的 iframe。

為興趣群組指定廣告

ads 和 adComponents 物件包含廣告素材的網址，以及選用的任意網址這些中繼資料。例如：

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

買方如何出價？

興趣群組擁有者提供的 biddingLogicUrl 指令碼必須包含 generateBid() 函式。當廣告空間賣方呼叫 navigator.runAdAuction() 時，generatedBid() 函式，系統會針對瀏覽器所屬的每個興趣群組呼叫一次函式 (在群組擁有者已受邀參與競標。換句話說，針對每個候選人呼叫 generateBid() 一次廣告。賣方針對傳遞的競價設定參數提供 decisionLogicUrl 屬性至 navigator.runAdAuction()。這個網址的程式碼必須包含 scoreAd() 函式，為參與競價的每一個出價工具進行出價，以便為 generateBid() 傳回的每筆出價評分。

注意：biddingWasmHelperUrl 是選用屬性，但可讓出價方提供 WebAssembly 中會耗用大量運算資源的子處理常式，從 biddingLogicUrl 提供的 JavaScript 函式驅動，而非 JavaScript。如果時，它必須指向透過 application/wasm mimetype 傳送的 WebAssembly 二進位檔。瀏覽器會將對應的 WebAssembly.Module 提供給 generateBid() 函式。

廣告空間買方提供的 biddingLogicUrl 指令碼必須包含 generateBid() 函式。每個候選廣告都會呼叫此函式一次。runAdAuction()敬上分別檢查每個廣告及其相關出價和中繼資料，然後替廣告指派他們的期望分數

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() 會使用下列引數：

interestGroup
廣告買方傳遞至 joinAdInterestGroup() 的物件。(興趣群組可透過 dailyUpdateUrl 更新)。
auctionSignals
傳遞至競價設定引數的屬性 navigator.runAdAuction()，由廣告空間賣方提供。這會提供頁面關聯資訊 (例如廣告大小和發布商 ID)、競價類型 (最高價得標競價或次高價) 等等中繼資料。
perBuyerSignals
與 auctionSignals 一樣，競價設定的屬性賣方傳遞至 navigator.runAdAuction() 的引數這能提供背景資訊買方伺服器傳送的網頁內容相關信號 (如果賣方是SSP) 會對買方伺服器執行即時出價呼叫，並負責回傳回應，或如果發布商直接與買方伺服器聯絡。如果是的話，買方可能會想檢查密碼編譯並可在 generateBid() 中納入這些信號，以防範竄改行為。
trustedBiddingSignals
該物件的鍵是 trustedBiddingSignalsKeys 興趣群組，以及 trustedBiddingSignals 要求中傳回其值。
browserSignals
由瀏覽器建構的物件，可能含有網頁相關資訊背景資訊 (例如目前網頁的 hostname，賣方可能會假冒) 和資料，裝置端展示頻率上限)。

browserSignals 物件的屬性如下：

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

如要計算 bid 值，generateBid() 中的程式碼可以使用函式的參數。例如：

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() 會傳回包含四個屬性的物件：

ad
廣告的任意中繼資料，例如賣方預期瞭解此出價的資訊；廣告素材。賣方](/privacy-sandbox/resources/glossary#ssp) 在競價和決策過程中使用這項資訊廣告素材。賣方會在競價和決策時使用這項資訊邏輯。
bid
參加競價的數值出價。賣方必須處於競爭狀態才能比較不同買方的出價，因此出價必須屬於賣方選用的單位 (例如，「每。如果出價為 0 或負數，此興趣群組就不會參加賣方的競價透過這個機制，買方就可以根據廣告不一定會顯示
render
在此出價贏得競價時，用於顯示廣告素材的網址或網址清單。 (請參閱部分)。值必須符合以下其中一個renderUrl 為興趣群組定義的廣告。
adComponents
選用，最多包含 20 個元件廣告包含多個元素取自興趣群組引數的 adComponents 屬性傳遞至 navigator.joinAdInterestGroup()。

要求瀏覽器退出興趣群組

興趣群組擁有者可以要求將瀏覽器從興趣群組中移除。在其他字詞，系統會要求瀏覽器從其所屬興趣群組清單中移除該興趣群組。

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

如果使用者回到要求瀏覽器新增興趣群組的網站，興趣群組擁有者就會成為興趣群組擁有者可以呼叫 navigator.leaveAdInterestGroup() 函式，要求瀏覽器移除興趣群組。廣告的程式碼也可以針對其興趣群組呼叫此函式。

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

稍後，該使用者前往銷售廣告空間的網站，在本例中為新聞網站。網站有廣告空間，也就是透過程式輔助方式販售的廣告空間即時出價。

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

插圖：使用者正在使用筆電的瀏覽器查看新聞網站。廣告
以及使用 Protected Audience API 進行的競價。

說明部分： 賣方進行裝置端競價

廣告競價可能會由發布商的 SSP 執行發布商本身競價的用意是為單一廣告選擇最適當的廣告這樣就能產生目前網頁的可用廣告版位競價會將興趣群組以及來自廣告空間買方和鍵/值服務賣方的資料。

廣告空間賣方透過呼叫 navigator.runAdAuction()。

例如：

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() 會傳回可解析為 URN (urn:uuid:<something>) 的承諾，廣告競價結果。只有在傳遞至圍欄頁框時，瀏覽器才能解碼這個影格以便顯示：發布商網頁無法檢查勝出的廣告。

注意：如先前所述， joinAdInterestGroup()必須與興趣群組擁有者的因此需要從 iframe 呼叫 joinAdInterestGroup() (例如來自需求端平台的流量)，除非興趣群組擁有者的來源與目前設定的來源相同文件 (例如有專屬興趣群組的網站)。 runAdAuction 沒有相同的要求，因此從runAdAuction() <script>代碼的成效可能遠高於跨來源 iframe。

decisionLogicUrl 指令碼會考量每則廣告及其相關出價中繼資料，則一次指定一個數值，然後以數值表示的理想度分數。

`auctionConfig` 個房源

屬性	必填	範例	角色
`seller`	必填	`'https://ssp.example'`	賣方的來源。
`decisionLogicUrl`	必填	`'https://ssp.example/auction-decision-logic.js'`	競價小程式 JavaScript 的網址。
`trustedScoringSignalsUrl`	選用	`'https://ssp.example/scoring-signals'`	賣家受信任伺服器的網址。
`interestGroupBuyers*`	必填	`['https://dsp.example', 'https://buyer2.example', ...]`	要求在競價中出價的所有興趣群組擁有者來源。
`auctionSignals`	選用	`{...}`	賣方資訊，例如網頁情境、競價類型等。
`sellerSignals`	選用	`{...}`	根據發布商設定、內容相關廣告請求等因素顯示的資訊
`sellerTimeout`	選用	`100`	賣方 `scoreAd()` 指令碼的執行階段上限 (毫秒)。
`perBuyerSignals`	選用	`{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ...}`	與每個買方在自家伺服器上的網頁內容相關信號。
`perBuyerTimeouts`	選用	`50`	特定買方 `generateBid()` 指令碼的執行時間上限 (毫秒)。
`componentAuctions`	選用	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	元件競價的其他設定。

* 賣方可以指定 interestGroupBuyers: '*'，允許所有興趣群組出價。然後根據興趣群組擁有者以外的條件決定是否接受廣告。舉例來說，賣方可以查看廣告素材是否符合他們的政策規定。

** 目前的 Protected Audience 實作不支援 additionalBids。閱讀競價參與者一節中的 Protected Audience 詳細說明。

系統如何挑選廣告？

decisionLogicUrl 的程式碼 (傳遞至 runAdAuction())，必須包含 scoreAd() 函式。每個廣告都執行一次以確定該有多好

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() 會使用下列引數：

adMetadata
買方提供的任意中繼資料。
bid
以數值表示的出價金額。
auctionConfig
傳遞至 navigator.runAdAuction() 的競價設定物件。
trustedScoringSignals
在競價期間從賣方的受信任伺服器擷取的值，。
browserSignals
瀏覽器建構的物件，包括瀏覽器提供的資訊，以及賣方的競價指令碼，藉此驗證下列資訊：

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

在競價開始之前，賣方會找出最適合可用的廣告版位的內容相關廣告。所屬國家/地區其 scoreAd() 邏輯會拒絕任何無法勝過內容相關廣告勝出的廣告。

5. 賣方和參與買方從「鍵/值」服務接收即時資料

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

說明部分： 從 Protected Audience 鍵/值服務擷取即時資料。

在廣告競價期間，廣告空間賣方可透過下列方式取得特定廣告素材的即時資料：使用以下項目的 trustedScoringSignalsUrl 屬性向鍵/值服務提出要求傳遞至 navigator.runAdAuction() 的競價設定引數與鍵來自 ads 和 adComponents 欄位中所有項目的 renderUrl 屬性參與競價的興趣群組

同樣地，廣告空間買方也可使用興趣群組引數的 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 屬性已傳遞至 navigator.joinAdInterestGroup()。

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

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

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

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

重點：在目前測試 Protected Audience 的初始實驗階段中，trustedBiddingSignalsUrl 必須具有與興趣群組擁有者相同的來源：請參閱「興趣群組屬性」和使用自己的伺服器。

6. 放送勝出的廣告

插圖：使用者正在使用筆電的瀏覽器查看新聞網站。廣告
腳踏車廣告 (8 折) 就會顯示，並在上方加入鎖頭圖示，表示廣告會在
圍欄。

說明部分： 瀏覽器顯示勝出廣告

如先前所述：runAdAuction() 傳回的承諾會解析為 URN 會傳遞到圍欄頁框進行轉譯，然後網站就會顯示。

7. 系統回報競價結果

說明部分： 事件層級報表 (目前)

注意：我們的長期計畫是為了讓瀏覽器記錄賣方和買方的競價結果使用匯總報表 API 做為暫時性的事件層級回報機制，將 reportResult() 賣方和得標出價方的 reportWin() 可以呼叫 sendReportTo() 函式。這需要單一引數：代表在競價完成後擷取的網址字串，用於回報要回報的事件層級資訊

賣方回報結果

說明部分： 有關轉譯的賣家報表

賣方在 decisionLogicUrl 提供的 JavaScript (也提供 scoreAd()) 可以加入 reportResult() 函式，回報競價結果。

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

傳遞至這個函式的引數如下：

auctionConfig
傳遞至 navigator.runAdAuction() 的競價設定物件。

browserSignals 個
由瀏覽器建構的物件，提供競價相關資訊。例如：

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

此函式的傳回值會做為得標出價方的 sellerSignals 引數 reportWin() 函式。

得標出價報表結果

說明部分： 「轉譯和廣告事件」的買方報表

得標出價方的 JavaScript (也提供了 generateBid()) 可包含使用 reportWin() 函式回報競價結果。

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

敬上

注意：如未定義 reportWin()，Chrome 中目前採用 Protected Audience 將發出警告。

傳遞至這個函式的引數如下：

「auctionSignals」和「perBuyerSignals
」傳遞給得標出價方的 generateBid() 值。
sellerSignals
reportResult() 的傳回值，可讓賣方可以將資訊傳遞給買方

browserSignals
由瀏覽器建構的物件，提供競價相關資訊。例如：

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

暫時損失/勝利報表導入

Chrome 暫時提供兩種競價報表的方法：

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

這些方法每個方法都會使用單一引數：競價完成後要擷取的網址。他們可以可以透過不同的網址引數，在 scoreAd() 和 generateBid() 中多次呼叫。

只有在競價完成時，Chrome 才會傳送偵錯損失/成功報表。如果競價是已取消 (例如因為使用新的導覽選項) 而產生任何報表。

根據預設，Chrome 提供這些方法。如要測試方法，請在 chrome://settings/adPrivacy 中啟用所有廣告隱私權 API。如果您在 Chrome 中使用指令列旗標來啟用 Protected Audience，請加入 BiddingAndScoringDebugReportingAPI 標記來明確啟用方法。如果旗標未啟用時，此方法仍可使用，但不會執行任何動作。

8. 回報一次廣告點擊

插圖
一個人在圍欄頁框中點擊單車廣告，或是在新聞網站上點擊了某則單車廣告
傳送給賣方和買方的資料

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

下圖說明 Protected Audience 廣告競價的各個階段：

Protected Audience 與 TURTLEDOVE 有何不同？

Protected Audience 是 TURTLEDOVE 提案系列在 Chromium 中實際導入的第一項實驗。

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

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

瀏覽器 (而非廣告客戶) 擁有廣告客戶的看法相關資訊感興趣的人
廣告客戶可以根據興趣放送廣告，但不能將興趣結合其他興趣特定使用者的相關資訊，特別是他們的身分或造訪的網頁。

Protected Audience 是從 TURTLEDOVE 推動而來，並準備一系列相關提案，以便為使用 API 的開發人員提供更完善的服務：

在 SPARROW 中： Criteo 提議將 (「總機人員」) 服務模型是在受信任的執行環境 (TEE) 中執行。Protected Audience 包含較有限的 TEE 用途，可用於即時資料查詢和匯總報表。
NextRoll 的《TERN》和 Magnite 的專輯 PARRROT 提案說明瞭買方和賣方在裝置端競價中扮演的不同角色。 Protected Audience 的廣告出價/評分流程是以這項工作為基礎。
RTB House 的依據結果和產品層級 TURTLEDOVE 修改作業改善了裝置端競價的匿名模型和個人化功能
PARAKEET 是 Microsoft 針對 TURTLEDOVE 類型廣告服務提出的提案，這類廣告服務仰賴在 TEE 中運作的 Proxy 伺服器以便將廣告請求去識別化，並保障隱私權資源。Protected Audience 尚未採用這個 Proxy 模型。我們即將推出 JavaScript API 使 PARAKEET 和 Protected Audience 保持一致，並支援日後的工作，進一步結合最佳同時介紹兩項提案

Protected Audience 尚未防止網站的廣告聯播網得知使用者會看到哪些廣告。我們希望，逐步提升 API 的隱私性。

可以使用哪些瀏覽器設定？

使用者可以啟用或停用 Chrome 的 Privacy Sandbox 試用計畫，頂層設定，位於 chrome://settings/adPrivacy 中。在初期測試期間可使用這項概略的 Privacy Sandbox 設定停用 Protected Audience。Chrome 計劃使用者查看及管理他們在網路上加入的興趣群組清單。和 Privacy Sandbox 技術本身一樣，使用者設定可能會根據使用者、監管機構等機構的意見回饋不斷調整。

隨著 Protected Audience 提案的進展，我們會繼續更新 Chrome 的可用設定 (以測試和意見回饋我們預計在日後提供更精細的設定，以便管理 Protected Audience 和相關資料。

當使用者以無痕模式瀏覽網頁，且成員資格處於無痕模式時，API 呼叫端無法存取群組成員已在使用者清除其網站資料後移除。

互動及分享意見回饋

GitHub：閱讀提案，提出問題並追蹤討論。
W3C：在「改善網路廣告業務」中討論業界的應用實例群組。
開發人員支援：您可以提問或參與 Privacy Sandbox 開發人員支援存放區。
FLEDGE 郵寄清單：fledge-api-announce 提供了 API 的相關公告和最新資訊
加入 Protected Audience 排定的呼叫 (每次第二週)。大家都歡迎加入 — 參加前，請務必加入 WICG。您可以積極參與，也可以純粹聆聽！
請填寫 Privacy Sandbox 意見回饋表單，在公開論壇外，與 Chrome 團隊私下分享意見。

取得支援

如有關於實作項目、示範或說明文件的問題，請執行下列操作：

提出新問題前往 privacy-sandbox-dev-support 存放區請務必選取 Protected Audience 的問題範本。
提報 GitHub 上的示範程式碼存放區問題。
如果有更廣泛的問題，說明如何透過 API 滿足您的用途，在提案存放區回報問題。

如果是在 Chrome 中導入 Protected Audience API 的錯誤和問題，請按照下列步驟操作： * 查看現有問題給 API 報告 * 請至 crbug.com/new 提出新問題。

取得最新消息

如要接收 API 的狀態變更通知，請加入開發人員。
如要密切追蹤 API 中所有正在進行的討論，請點選「提案」頁面上的「觀看」按鈕 GitHub。您必須有或建立 GitHub 帳戶。
如要取得 Privacy Sandbox 的整體最新消息，請訂閱 RSS 動態消息 [隱私權說明進度] 沙箱]。

瞭解詳情

Protected Audience API：較少提案的技術總覽。
Protected Audience 示範：基本 Protected Audience 部署的逐步操作說明。
Protected Audience 示範影片：說明範例程式碼，並示範如何使用 Chrome 開發人員工具進行 Protected Audience 偵錯。
Protected Audience API 技術說明
深入瞭解 Privacy Sandbox
意圖建立原型

相片來源：Ray Hennessy 在 Unsplash 網站上。