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

FLEDGE API 開發人員指南
bookmark_border 透過集合功能整理內容你可以依據偏好儲存及分類內容。

這篇文章適用對象

本文是目前 Protected Audience API 實驗版的技術參考資料。

Protected Audience API 是提案的非技術性總覽，並提供專有名詞解釋。
Protected Audience 範例會逐步介紹基本 FLEDGE 部署作業。
Protected Audience 示範影片說明示範程式碼的運作方式，並示範如何使用 Chrome 開發人員工具進行 Protected Audience 偵錯。

什麼是 Protected Audience？

Protected Audience API 是一種運用 Privacy Sandbox 技術的提案，用來服務再行銷和自訂目標對象用途，設計方針是讓第三方無法追蹤使用者的跨網站瀏覽行為。這個 API 可讓瀏覽器進行裝置端競價，為使用者先前造訪的網站選擇相關廣告。

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

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

如何試用 Protected Audience？

Protected Audience 試播

如要瞭解如何在廣告主和發布商網站上部署基本 Protected Audience，請前往 protected-audience-demo.web.app。

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

參與 Protected Audience 來源試用

在 Chrome Beta 101.0.4951.26 以上版本的桌上型電腦上，已針對 Protected Audience、Topics 和 Attribution Reporting API 推出 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 Code Search。

最新版 Chrome 支援哪些功能？

我們在 Chromium 中提供 Protected Audience 功能旗標，做為第一個實驗，以測試 Protected Audience 提案的下列功能：

興趣群組：由瀏覽器儲存，並附帶相關中繼資料，用於設定廣告出價和顯示。
買方 (需求端平台或廣告主) 的裝置端出價：根據儲存的興趣群組和賣方提供的信號。
賣家 (SSP 或發布商) 在裝置端執行廣告選擇作業：根據競價出價和買方的中繼資料。
在暫時放寬的 Fenced Frames 版本中顯示廣告：允許廣告顯示功能存取網路和記錄。

API 說明文件會進一步說明功能支援和限制。

興趣群組權限

目前 Protected Audience 的實作方式預設為允許從網頁中的任何位置，甚至跨網域 iframe 呼叫 joinAdInterestGroup()。日後，當網站擁有者有時間調整跨網域 iframe 權限政策後，我們將禁止跨網域 iframe 的呼叫，如說明所述。

鍵/值服務

在 Protected Audience 廣告競價期間，瀏覽器可以存取鍵/值服務，傳回簡單的鍵/值組合，為廣告買方提供資訊，例如剩餘的廣告活動預算。Protected Audience 提案規定，此伺服器「不會執行事件層級記錄作業，也不會根據這些要求出現其他副作用」。

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

初步測試時，我們會使用「自備伺服器」模式。長期來說，廣告技術需要使用在受信任的執行環境中執行的開放原始碼目標對象鍵/值服務，才能擷取即時資料。

為確保生態系統有足夠的時間進行測試，我們不會在第三方 Cookie 淘汰後立即要求使用開放原始碼鍵/值服務或 TEE。我們會提前通知開發人員，讓他們在轉換作業開始前開始測試及採用。

偵測功能支援

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

無論您是網站擁有者或個別使用者，都可以封鎖 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 的使用情形，請在 iframe 元素中加入下列 allow 屬性：

<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 工作項進行偵錯。

第一步是透過「來源」面板中的「Event Listener Breakpoints」分頁，在新的類別中設定中斷點。

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

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

即時工作區別的程式碼也會顯示在「執行緒」面板下方。

Chrome Canary 中的開發人員工具螢幕截圖，其中「來源」面板中以高亮顯示「執行緒」窗格，顯示目前已暫停的 worklet 指令碼。

由於部分工作項可能會並行執行，因此多個執行緒可能會處於「暫停」狀態；您可以使用執行緒清單在執行緒之間切換，並視需要繼續或更仔細地檢查。

觀察 Protected Audience 事件

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

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

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

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

Chrome Canary 中的「開發人員工具」應用程式面板，顯示目標對象受保護競價和得標事件的相關資訊。

Protected Audience API 如何運作？

在這個範例中，使用者瀏覽自訂自行車製造商的網站，之後再造訪新聞網站，並且看到該自行車製造商的新款自行車廣告。

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

假設使用者造訪客製自行車製造商 (本例中的廣告主) 網站，並在手工鋼製自行車的產品頁面停留一段時間。這為自行車製造商提供了再行銷機會。

2. 要求使用者的瀏覽器加入興趣群組

插圖：顯示使用者在筆電的瀏覽器中瀏覽網站。JavaScript 程式碼 joinAdInterestGroup() 在瀏覽器中執行。

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

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

注意：joinAdInterestGroup() 呼叫內容的來源必須與興趣群組擁有者的來源相符，因此必須從 iframe (例如 DSP) 呼叫 joinAdInterestGroup()，除非興趣群組擁有者的來源與目前文件的來源相符 (例如擁有自有興趣群組的網站)。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 的實作方式預設為允許從網頁任何位置 (甚至跨來源 iframe) 呼叫 joinAdInterestGroup()。日後，當網站擁有者有時間調整權限政策後，這項計畫將預設為禁止跨來源 iframe 的呼叫，如「Protected Audience」說明所述。

興趣群組擁有者的許可

只要從與興趣群組擁有者相同來源的 iframe 呼叫 joinAdInterestGroup()，系統就會隱含授予興趣群組擁有者權限。舉例來說，dsp.example iframe 可以為 dsp.example 擁有的興趣群組呼叫 joinAdInterestGroup()。

建議做法是讓 joinAdInterestGroup() 在擁有者網域中的網頁或 iframe 中執行，或是透過 .well-known 網址的清單，將 joinAdInterestGroup() 委派給其他網域。

使用 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 KiB，否則呼叫會失敗。第二個參數會指定興趣群組的時間長度，上限為 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 中指定的欄位。不過，呼叫 navigator.joinAdInterestGroup() 會覆寫任何現有的興趣群組。

更新作業是盡力而為，可能會在下列情況下失敗：

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

如果更新時間連續過長，系統也會取消更新，但不會對取消的 (剩餘) 更新施加任何速率限制。更新頻率上限為每天一次。系統會在 1 小時後重試因網路錯誤而失敗的更新，並在重新連線後立即重試因網路中斷而失敗的更新。

手動更新

您可以透過 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() 的競價設定引數屬性。如果賣方是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
廣告的任意中繼資料，例如賣方想瞭解的出價或廣告素材相關資訊。賣方](/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 (例如 DSP) 呼叫 joinAdInterestGroup()。runAdAuction 沒有相同的要求，因此從 <script> 標記呼叫 runAdAuction() 的效能可能比跨來源 iframe 高出許多。

decisionLogicUrl 指令碼會逐一考量每個個別廣告及其相關出價和中繼資料，然後指派數值可取度分數。

`auctionConfig` 個房源

屬性	必填	範例	角色
`seller`	必填	`'https://ssp.example'`	賣家的來源。
`decisionLogicUrl`	必填	`'https://ssp.example/auction-decision-logic.js'`	競價 Worklet 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 物件，可提供各個鍵的值。

重點：在目前測試受保護目標對象的初期實驗階段，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. 回報廣告點擊

系統會記錄在圍欄框架中顯示的廣告點擊次數。如要進一步瞭解這項功能的運作方式，請參閱「Fenced Frames Ads Reporting」。

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

Protected Audience 和 TURTLEDOVE 有何不同？

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

Protected Audience 遵循 TURTLEDOVE 的整體原則。部分線上廣告會根據使用者先前與廣告客戶或廣告聯播網互動的情況，向可能感興趣的使用者放送廣告。以往廣告主會在使用者瀏覽各個網站時辨識特定使用者，這也是現今網路上最主要的隱私權問題。

TURTLEDOVE 計畫旨在提供新的 API 來處理這項用途，同時提供一些重要的隱私權進展：

瀏覽器 (而非廣告主) 會保留廣告主認為使用者感興趣的資訊。
廣告主可以根據興趣放送廣告，但不得將該興趣與使用者的其他資訊 (特別是使用者身分或造訪的網頁) 結合。

Protected Audience 源自於 TURTLEDOVE 和一系列相關的修改提案，可為使用 API 的開發人員提供更完善的服務：

在 SPARROW 中：Criteo 建議新增在受信任的執行環境 (TEE) 中執行的服務模型 (「Gatekeeper」)。Protected Audience 會使用較受限的 TEE，以便即時查詢資料和匯總報表。
NextRoll 的 TERN 和 Magnite 的 PARRROT 提案說明瞭買方和賣方在裝置端競價中的不同角色。Protected Audience 的廣告出價/評分流程就是以這項工作為基礎。
RTB House 的以成效為準和產品層級 TURTLEDOVE 修改內容，改善了裝置端競價的匿名模型和個人化功能
PARAKEET 是 Microsoft 提出的 TURTLEDOVE 類廣告服務提案，該服務會在瀏覽器和廣告技術供應商之間的 TEE 中執行 Proxy 伺服器，以匿名廣告請求和強制執行隱私權屬性。Protected Audience 並未採用這種代理模式。我們會將 PARAKEET 和 Protected Audience 的 JavaScript API 對齊，以便日後進一步結合這兩項提案的最佳功能。

目前 Protected Audience 無法防止網站廣告聯播網瞭解使用者看到哪些廣告。我們預計會修改 API，讓 API 日後更注重隱私權。

可用的瀏覽器設定為何？

使用者可以透過啟用或停用 chrome://settings/adPrivacy 中的頂層設定，調整在 Chrome 中參與 Privacy Sandbox 試驗的情況。在初步測試期間，使用者可以使用這項高層級 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 動態消息 [Progress in the Privacy Sandbox]。

瞭解詳情

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

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

FLEDGE API 開發人員指南 bookmark_borderbookmark 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

這篇文章適用對象

什麼是 Protected Audience？

如何試用 Protected Audience？

Protected Audience 試播

參與 Protected Audience 來源試用

測試這個 API

在 iframe 或區隔的框架中顯示廣告

最新版 Chrome 支援哪些功能？

興趣群組權限

鍵/值服務

偵測功能支援

如何選擇不採用 Protected Audience？

網站如何控管存取權？

使用者選擇停用

偵錯 Protected Audience 工作區

觀察 Protected Audience 事件

Protected Audience API 如何運作？

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

2. 要求使用者的瀏覽器加入興趣群組

造訪網站的權限

興趣群組擁有者的許可

使用 navigator.joinAdInterestGroup()

興趣群組屬性

更新興趣群組屬性

手動更新

自動更新

指定興趣群組的廣告

買家如何出價？

要求瀏覽器退出興趣群組

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

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

auctionConfig 個房源

廣告如何選取？

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

6. 顯示得標廣告

7. 回報競價結果

賣家回報結果

得標廣告客戶回報結果

暫時性損益報表導入

8. 回報廣告點擊

Protected Audience 和 TURTLEDOVE 有何不同？

可用的瀏覽器設定為何？

互動及分享意見回饋

取得支援

取得最新消息

瞭解詳情

FLEDGE API 開發人員指南
bookmark_border 透過集合功能整理內容你可以依據偏好儲存及分類內容。

`auctionConfig` 個房源