本頁面由 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 追蹤使用者的跨網站瀏覽行為。這個 API 可讓瀏覽器啟用裝置端競價，針對使用者造訪過的網站選擇相關廣告。

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

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

如何試用 Protected Audience？

Protected Audience 示範

如需廣告主和發布商網站的基本 Protected Audience 部署作業，請參閱 Protect-audience-demo.web.app。

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

參與 Protected Audience 來源試用

對於 Protected Audience、Topics 和 Attribution Reporting API，電腦版的 Chrome Beta 版 101.0.4951.26 以上版本已提供 Privacy Sandbox 關聯性和評估來源試用功能。

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

成功註冊試用後，您可以在提供有效試用權杖的網頁上試用 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 功能。這有助於確保未經網站同意，任意第三方無法使用 API。不過，為了方便在首次來源試用期間進行測試，預設免除這項要求。如果想在測試期間明確停用 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」或來自 chrome://settings/cookies 的「封鎖所有 Cookie」。
使用無痕模式。

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

偵錯 Protected Audience 功能

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

第一步是在「Sources」面板中的「Event Listener Breakpoints」窗格中，透過新類別設定中斷點。

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

中斷點觸發時，系統會先暫停執行，再由工作站指令碼頂層的第一個陳述式執行。您可以使用一般中斷點或步驟指令，取得出價/評分/報表函式本身。

即時 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
程式碼 joinAdInterestGroup()。

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

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

注意：joinAdInterestGroup() 的呼叫結構定義來源必須與興趣群組擁有者的來源相符，因此除非興趣群組擁有者的來源與目前文件的來源相符 (例如具有專屬興趣群組的網站)，否則必須透過 iframe 呼叫 joinAdInterestGroup() (例如從 DSP 呼叫)。 runAdAuction 沒有相同的要求，因此從 <script> 標記呼叫 runAdAuction() 的成效可能遠高於跨來源 iframe。

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

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

例如，若沒有 dsp.example 權限，malicious.example 就無法以 dsp.example 的擁有者身分呼叫 joinAdInterestGroup()。

來自所造訪網站的權限

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

跨來源：如要成功呼叫來自目前網頁來源的 joinAdInterestGroup()，您必須設定權限政策，允許從跨來源 iframe 呼叫 joinAdInterestGroup()。

注意：目前的 Protected Audience 實作預設會允許從網頁中的任何位置呼叫 joinAdInterestGroup()，甚至是跨來源 iframe 呼叫。日後網站擁有者有時間調整權限政策後，計畫會預設為禁止來自跨來源 iframe 的呼叫，如 Protected Audience 說明所述。

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

只要從來源與興趣群組擁有者相同的 iframe 呼叫 joinAdInterestGroup()，即可間接授予興趣群組擁有者權限。舉例來說，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 網址提供。有關如何在本機執行 Protected Audience 的說明，請參閱「如何使用 HTTPS 進行本機開發」。此外，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 中指定的欄位會更新)，呼叫 navigator.joinAdInterestGroup() 則會覆寫任何現有興趣群組。

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

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

如果更新時間的連續時間過多，也可以取消更新。不過，這並未針對取消 (剩餘) 的更新強制實行任何頻率限制。更新頻率的限制為每天一次。如果更新作業因網路錯誤而失敗，系統會在一小時後重試；而因網際網路連線中斷而失敗的更新，會在重新連線時立即重試。

手動更新

你可以透過 navigator.updateAdInterestGroups() 手動觸發目前影格來源擁有的興趣群組更新。頻率限制可避免更新太頻繁：重複呼叫 navigator.updateAdInterestGroups() 在頻率限制期間 (目前為一天) 之前都不會執行任何動作。如果針對同一個興趣群組 owner 和 name 再次呼叫 navigator.joinAdInterestGroup()，頻率限制就會重設。

自動更新

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

為興趣群組指定廣告

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

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

買方如何出價？

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

注意：biddingWasmHelperUrl 是選用屬性，但可讓出價工具在 WebAssembly 中提供運算成本高昂的子處理常式，而非 JavaScript 這個子處理常式，由 biddingLogicUrl 提供的 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()。如果賣方是對買方伺服器執行即時出價呼叫並傳遞回應的賣方平台，或是發布商頁面直接與買方伺服器聯絡，這就能提供來自買方伺服器的網頁相關比對內容信號。如果是的話，買方可以在 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
參加競價的數字出價。賣方必須處於某個位置，才能比較不同買方的出價，因此出價必須採用賣方所選單位 (例如「每千美元」)。如果出價為零或負值，這個興趣群組就完全不會參與賣家的競價。透過這個機制，買方就可以導入任何廣告客戶規則，決定廣告能否顯示的位置。
render
在這項出價贏得競價時用於顯示廣告素材的網址或網址清單。 (請參閱 API 說明中的「由多種管道組合的廣告」)。這個值必須符合為興趣群組定義的廣告的 renderUrl。
adComponents
選用清單，可顯示最多 20 個元件，用於由多個部分組成的廣告，取自傳遞至 navigator.joinAdInterestGroup() 的興趣群組引數的 adComponents 屬性。

要求瀏覽器退出興趣群組

興趣群組擁有者可以要求將瀏覽器從興趣群組中移除。換句話說，瀏覽器會要求瀏覽器從其所屬群組清單中移除興趣群組。

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 沒有相同的要求，因此從 <script> 標記呼叫 runAdAuction() 的成效可能遠高於跨來源 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 API 進行廣告競價，期間會讓參與者從鍵/值服務取得資料。

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

在廣告競價期間，廣告空間「賣方」可以使用向 navigator.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 的目前初始實驗階段，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>
}

此函式的傳回值會用作得標出價工具 reportWin() 函式的 sellerSignals 引數。

得標出價報表結果

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

得標出價方的 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. 回報一次廣告點擊

插圖顯示使用者點選單車廣告，位於新聞網站中的圍欄頁框中，並提供向賣家和買家提供的報表資料。

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

下圖說明 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 模型。我們將提供 PARAKEET 和 Protected Audience 的 JavaScript API，支援日後的工作模式，進一步結合這兩種提案的最佳功能。

Protected Audience 尚未防止網站的廣告聯播網得知使用者會看到哪些廣告。我們預計會持續修改這個 API，提高隱私性。

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

使用者可以在 chrome://settings/adPrivacy 中啟用或停用頂層設定，調整自己在 Chrome 的 Privacy Sandbox 試用計畫參與進度。在初始測試期間，使用者可以使用這項高階 Privacy Sandbox 設定停用 Protected Audience。Chrome 計劃讓使用者查看及管理他們在造訪過的網站上新增的興趣群組清單。如同 Privacy Sandbox 技術本身，使用者設定也可以根據使用者、監管機構和其他人員的意見回饋，進行改善。

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

使用者以無痕模式瀏覽時，API 呼叫端無法存取群組成員，而使用者清除網站資料後，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 動態消息 [ID 中的進度]。

瞭解詳情

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

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