Protected Audience API 競價報表

評估 Protected Audience API 競價資料和結果

本文概略說明可透過哪些機制向伺服器回報 Protected Audience API 競價資料，以及目前可在遷移期間使用的轉換機制，直到替代解決方案準備就緒為止。

為了針對您從廣告競價收集到的重要指標製作報表，Protected Audience API 可與：

• 私密匯總：收集競價信號和結果，以便產生摘要報表。
• Ads Reporting API：適用於 Fenced Frame 和 iframe，此為影格中的管道，可用來與 Protected Audience API 小程式通訊。API 允許將事件層級資料與競價信號建立關聯。Ads Reporting API 的事件層級報表是一項轉場機制，直到設計出更私密的報表機制為止。
• Attribution Reporting：可讓您將轉換資料與競價信號建立關聯。
• 共用儲存空間：可讓您將競價信號寫入跨來源儲存空間，之後透過私密匯總功能回報這些資料。

注意：建議您先參閱私人匯總、Fenced Frames、共用儲存空間和 Attribution Reporting 相關說明文件，再繼續下一步，因為本文已詳細介紹核心概念。

Protected Audience API 報表總覽

Protected Audience 整體工作流程

在下列三個主要時間範圍內，系統會向您的伺服器回報 Protected Audience API 的競價流程資料：競價從發布商網站執行競價時的競價期間、廣告顯示於發布商網站中的圍欄或 iframe 的顯示時間，以及使用者在另一個網站上執行動作時，可歸因於競價。

在競價期間，您可以使用報表範本製作競價資料報表。在轉譯期間，您可以回報 iframe 或圍欄頁框的參與度資料。在轉換期間，您可以使用 Attribution Reporting API 記錄到達網頁的歸因資料。

報表位置

在競價中，買方可以回報 generateBid() 和 reportWin() 工作小程式提供的信號，賣方則可回報 scoreAd() 和 reportResult() 中可用的信號。在競價之外，買方和賣方可以記錄廣告所在的頁框，以及轉換的來源網站資料。

時間範圍	目的地	位置	有可用的資料	可使用 Reporting API
競價廣告空間	採購	generateBid()	信號、競價結果和競價成效	私密匯總 API
		reportWin()		Private Aggregation API Ads Reporting API
	賣方	scoreAd()		私密匯總 API
		reportResult()		Private Aggregation API Ads Reporting API
算繪	買家 / 賣家	發布商網站上的頁框	廣告頁框中的事件層級資料	Private Aggregation API Ads Reporting API
轉換	買家 / 賣家	轉換網站	轉換網站的轉換和事件層級資料	Attribution Reporting API Private Aggregation API Ads Reporting API

在所列每個時間範圍內，買方和賣方可以存取各種報表 API 來製作報表，例如競價信號、事件層級資料和轉換資料。

Protected Audience API 競價期間可使用的資料

系統會在競價期間透過 Protected Audience API 工作小程式回報下列資料。

信號

信號是競價情境資料、使用者資料、即時資料和瀏覽器資料，可供買方和賣方在 Worklet 中產生出價、為廣告評分及回報競價結果。

信號	說明	設定位置	使用者	適用地區
auctionSignals	系統在競價期間提供的資料。這類資料包括網頁內容資訊、第一方使用者資料等。	由賣方在競價設定中由發布商網站設定。	買方 賣家	generateBid ScoreAd reportWin reportResult
directFromSellerSignals	auctionSignals、perBuyerSignals 的資料與 sellerSignals 相同，但信號保證來自指定賣方。	透過賣方的 HTTP 回應標頭設定	買方 賣家	generateBid ScoreAd reportWin reportResult
browserSignals	瀏覽器提供的各種資料 (topWindowHostname、interestGroupOwner、renderUrl、adComponents、biddingDurationMsec、IGJoinCount、IGRecency、modelingSignals)。	由瀏覽器設定。	買方 賣家	generateBid ScoreAd reportWin reportResult
sellerSignals	提供給賣方用來廣告評分的信號。	由賣方在競價設定中由發布商網站設定。	賣方	ScoreAd reportWin reportResult
trustedScoringSignals	向賣方提供廣告評分的即時信號。	此網址是由賣方在競價設定中設定，	賣方	ScoreAd reportResult
perBuyerSignals	提供給特定買方的競價內容相關資料。賣方可以在競價開始前擷取買方的值。這是買方對廣告商機的瞭解。	由賣方在競價設定中由發布商網站設定。	採購	generateBid ScoreAd reportWin reportResult
trustedBiddingSignals	提供給買方用於廣告出價的即時信號。	此網址是由買方在已設定興趣群組時透過廣告客戶網站設定。	採購	generateBid
userBiddingSignals	買方提供的使用者資料。	設定興趣群組時，由廣告客戶網站的買方設定。	採購	generateBid

競價設定物件是所提供資料的主要來源，以做為 Worklet 中的信號。發布商和賣方可在競價設定中提供比對內容資料和第一方資料，系統也能利用買方的興趣群組資料、廣告顯示頁框的事件層級資料，以及來自到達網頁的歸因資料，充實這些信號。報表資料可用於買方/賣方報表、帳單、預算、機器學習模型訓練等。

其他可用資料

• 結果資料與競價勝出和損失資料有關，例如得標出價和出價遭拒原因。
• 成效資料，內含延遲時間資訊，例如擷取及執行出價工作小程式所需的時間。

Protected Audience API 競價外取得的資料

除了 Protected Audience API 競價以外，系統在兩個時間範圍內都可回報相關資料。

在算繪期間，當廣告在發布商網站上顯示時，iframe 或 Fenced Frame 內部的事件層級資料可能會與 Protected Audience API 競價資料建立關聯，並回報給伺服器。範例事件層級資料包括廣告曝光、點閱、懸停，以及影格內發生的任何其他事件。

在轉換期間內，當使用者在歸因於競價的到達網頁上採取某些動作時，轉換頁的事件層級資料就可以與 Protected Audience API 競價資料建立關聯，並記錄至您的伺服器。

事件層級報表

事件層級報表提供了一或多個事件的詳細資訊。事件可能是競價勝出、廣告曝光或轉換。至少到 2026 年之前，系統會保留事件層級競價勝出者報表，顯示 Protected Audience 廣告不需要設有圍欄頁框的情況；而具有不受限制網路存取權的 iframe 則可用於事件層級報表。此外，Ads Reporting API 也適用於圍欄頁框和 iframe，可讓您將競價和轉換資料與影格的事件層級資料建立關聯。這套解決方案可讓生態系統更容易遷移，因為在至少 2026 年之前，您可以繼續使用現有的報表基礎架構，並將系統遷移至 Protected Audience。

使用 sendReportTo() 完成事件層級競價勝出報表

系統運用一項機制，在 Protected Audience 競價中回報事件層級資料，是競價勝出情形的 sendReportTo() function。買方和賣方報表都能使用這個函式，瀏覽器在顯示廣告開始時，向提供的網址字串發出 GET 請求。您可以將 Worklet 中的任何信號編碼為網址的查詢參數。

舉例來說，買方可以回報 reportWin() 工作小程式的得標出價金額，以便計費：

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

從 reportResult() 呼叫時，sendReportTo() 函式可用來產生賣方勝出報表，而從 reportWin() 呼叫時，也可以為買方產生勝出報表。sendReportTo() 函式至少可使用至 2026 年，

「參與」報表

參與報表包含廣告素材的事件層級資料，例如曝光或點擊資料，與顯示廣告的 Protected Audience API 競價信號相關聯。由於廣告在競價結束後才顯示，因此顯示廣告的頁框中不會顯示競價信號。為了將這些資料與不同時間範圍建立關聯，我們提供兩種轉換機制來產生參與報表。

上述的 sendReportTo() 函式可用來將競價資料與 iframe 的事件層級資料建立關聯，但不適用於 Fenced Frame，因為嵌入程式與 Fenced Frame 之間的通訊受到限制。如要將競價資料與圍欄頁框廣告的事件層級資料建立關聯，可以使用 Ads Reporting API。

適用於圍欄頁框和 iframe 的 Ads Reporting API

您可以使用 Ads Reporting API，建立圍欄頁框和 iframe 的使用者事件層級資料，與 Protected Audience 競價中的信號建立關聯。

在 Protected Audience API 報表工作流程中，您可以使用 registerAdBeacon() 函式註冊廣告信標，並將加入做為查詢參數的信號傳入報表網址。您也可以指定要與報表網址建立關聯的自訂事件。之後當廣告在圍欄頁框中顯示時，您可以呼叫 window.fence.reportEvent() 函式觸發自訂事件。可以將 Fenced Frame 內可用的資料新增為酬載。

registerAdBeacon() 函式僅適用於報表函式，不適用於買方的出價邏輯和賣方的評分邏輯。

在以下範例中，廣告活動 ID 會與事件層級酬載與點擊座標建立關聯：

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

Fenced Frames Ads Reporting API 也將於至少 2026 年開放使用，但原因與勝出報表相同。

詳情請參閱說明。

不受限制的網路存取權

Fenced Frame 可讓您使用與 iframe 相同的方式載入網路資源，而且您可以將 Fenced Frame 內的事件層級資料傳送至伺服器。您可以稍後再在伺服器端產生事件層級報表，方法是將圍欄頁框的事件層級資料與與 sendReportTo() 傳送的競價資料建立關聯 (如上方「競價事件層級報表機制」一節所述)。

第三方 Cookie 淘汰之後，網路存取權將受到限制。

Protected Audience API 目前提供的事件層級檢舉機制是轉換機制，另外，還有替代解決方案將能更妥善地支援現有用途。

歸因報表

您可以使用歸因報表，將網站上的轉換與從 Protected Audience API 競價選出的廣告建立關聯。舉例來說，使用者可能會點選您放送的產品廣告，並重新導向至廣告客戶的網站、購買商品，而您想要將購買功勞歸給放送的廣告。Attribution Reporting API 將與 Protected Audience API 整合，以結合發布商網站的競價資料和廣告客戶網站的轉換資料。

在我們設計更具永久性的解決方案時，您可以搭配 Ads Reporting API 使用圍欄頁框，做為轉換機制，運用 Attribution Reporting 產生事件層級和可匯總報表。請注意，這些報表用於評估轉換，與競價和廣告頁框產生的事件層級和可匯總參與報表不同。準備就緒後，我們會發布說明，提供更永久的解決方案。

轉換機制

註冊廣告信標時，您可以使用關鍵字「reserved.top_navigation」，這項工具會自動加入信標 Attribution-Reporting-Eligible 標頭，藉此登錄為歸因來源。

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

如要將事件層級資料附加至您註冊的信標，您可以透過事件酬載從圍欄頁框呼叫 setReportEventDataForAutomaticBeacons()。

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

詳情請參閱 Ads Reporting API 說明中的 Attribution Reporting 一節。

參與度和轉換報表範例

在本例中，我們將以買方的角度看待如何將競價、廣告頁框和轉換網站的資料建立關聯。

在本工作流程中，買方會與賣方協調，將專屬 ID 傳送給競價。在競價期間，買方會透過競價資料傳送這個專屬 ID。在顯示和轉換期間，系統也會傳送 Fenced Frame 或 iframe 的資料，並使用相同的專屬 ID。日後，這個專屬 ID 可以用來將這些報表連結在一起。

工作流程：

1. 競價開始前，買方會在程式輔助即時出價 (「RTB」) 出價回應中，將專屬 ID 傳送給賣方。ID 可以設為 auctionId 等變數。ID 會在 auctionConfig 中以 perBuyerSignals 傳入，並會顯示在買家的 Worklet 中。
2. 在競價期間，買方可以註冊要在廣告顯示時間和轉換時間 (registerAdBeacon()) 觸發的廣告信標。
   1. 如要為廣告影格事件建立關聯競價信號，請將 auctionId 設為信標網址的查詢參數。
   2. 如要為轉換事件建立關聯競價信號，請在信標網址中設定 auctionId。
3. 在廣告顯示期間，系統可能會透過事件層級資料觸發或加強您在競價期間註冊的信標。
   1. 使用 reportEvent() 觸發影格事件，並傳入事件層級資料。
   2. 使用 setReportEventDataForAutomaticBeacons() 將事件層級酬載新增至歸因信標
   3. 以 Attribution-Reporting-Register-Source 標頭回應廣告信標請求，使用 Attribution Reporting API 註冊廣告。
4. 在轉換期間，您可以觸發競價期間登錄的來源。

完成上述程序後，買方會有競價報表、參與報表和轉換報表，並以一組專屬鍵連結彼此。

如果賣方需要存取歸因資料，也適用類似的工作流程，而賣方也可以使用專屬 ID 搭配 registerAdBeacon() 傳送。在頁框中，reportEvent() 呼叫包含目的地屬性，可用於將報表傳送給買方和賣方。請注意，到達網頁也必須有賣方平台，觸發條件才會歸因至來源。

匯總 Protected Audience 資料

Private Aggregation API 是 Protected Audience 資料的回報機制，可用來產生摘要報表，後者是彙整區塊中收集到的資料匯總報表，值區以匯總鍵表示，部分資訊則可編碼至鍵中。

舉例來說，系統會將廣告曝光事件歸入不同的值區，而每個區塊都代表不同的廣告活動。摘要報表與事件層級報表不同，不會顯示個別事件的相關資訊。透過事件層級報表，您可以得知使用者 A、B 和 C 看過廣告活動 123。您可以利用摘要報表評估看過廣告活動 123 並新增噪音的使用者人數，以保護使用者隱私。

如要進一步瞭解 API，請參閱私人匯總文章。

匯總競價信號

您可以利用「私密匯總」功能，將 Worklet 中的可用信號匯總至您的伺服器。如要匯總信號，您可以使用買方出價手冊、賣方評分手冊和買方/賣方報表工作流程中的 privateAggregation.contributeToHistogram() 方法。

在這個範例中，得標出價會匯總至興趣群組擁有者值區：

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

當您要匯總的信號與事件層級資料無關，且並非由競價以外的事件觸發時，就可以使用這個一般機制。如要進一步瞭解如何回報競價信號，請參閱說明。

使用事件資料匯總競價信號

你可以匯總競價信號，針對廣告頁框中發生的事件提供有限資訊。舉例來說，您可以建立代表該廣告活動和點擊事件的值區，匯總評估廣告活動的廣告點擊次數。請注意，您可以在廣告頁框中指定發生的事件，但無法附加事件層級酬載。

如要依事件匯總競價信號，您可以使用 privateAggregation.contributeToHistogramOnEvent(eventType, contribution) 接受字串，用於指定事件類型，以及在觸發該事件時要回報的貢獻。您可以使用自訂事件類型呼叫該方法，然後從廣告頁框呼叫 window.fence.reportEvent(eventType) 來觸發提交報表。

假設您想評估某個廣告活動的廣告獲得的點擊次數。

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

在出價產生函式中，您可以將值區定義為廣告活動 ID 和點擊事件的組合，然後在每次觸發事件時，將該區塊的值提高 1。

// Ad frame
window.fence.reportEvent('click');

之後，您可以在廣告頁框中呼叫 reportEvent(eventType) 來觸發報表提交作業：

如要進一步瞭解如何從影格觸發私人匯總貢獻，請參閱說明。

報表競價結果和成效

您也可以在傳遞預訂事件類型關鍵字 (reserved.win, reserved.loss 和 reserved.always) 時，使用 contributeToHistogramOnEvent(eventType, contribution) 匯總競價勝出或失敗事件所觸發的競價結果，

「私人匯總」會提供基準值清單，您可以計算貢獻內容的值區和價值。競價結果可用的基準值包括勝出廣告的出價值、評為第二高的出價值，以及出價未參與競價的原因。

如有提供特定基準價值 (例如得標出價金額)，你可以設定該值的增減量，然後回報最終值。舉例來說，如果得標出價是 NT $150 元做為基本價值，則只要將出價相減 $2 美元，即可算出競價失敗次數，也就是您錯失了 $3 美元的實際價值。

競價結果報表

讓我們用一個範例，瞭解您失去競價的原因，而您想瞭解自己的出價與競價結算價格之間有多少差距。

若要瞭解您贏得競價的程度，請從得標出價中減去出價價格：

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

提交報告後，實際回報的值將由 offset 值調整的 baseValue 值。詳情請參閱說明。

成效報表

買方和賣方可以回報指令碼的執行時間，以及擷取受信任信號所需的時間。賣方可以在獲得許可的情況下，收集每位買方的出價產生時間和受信任出價信號時間。

詳情請參閱說明。

在共用儲存空間中儲存競價信號

「共用儲存空間」是可自由寫入的未分區與跨來源儲存空間，但在讀取和處理儲存的值時，系統會設下閘門。Shared Storage API 可用的其中一個閘道為「私密匯總」。您只能從 Worklet 讀取共用儲存空間中的值，也可以使用 Worklet 中的 Private Aggregation 回報這些值。

您也可以透過 Protected Audience API 出價、評分和報表小工具寫入共用儲存空間。在稍後，您可以使用「私密匯總」功能，將共用儲存空間中的這些值回報給伺服器。您也可以使用儲存的值進行「URL Selection」作業。

透過 Protected Audience API 工作區，您可以將任何鍵和值寫入共用儲存空間：

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

稍後，您可以載入共用儲存空間工作小程式，然後使用「私密匯總」功能讀取並傳送該值：

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

如要進一步瞭解共用儲存空間，請參閱 Protected Audience API 報表開發人員指南中的共用儲存空間部分、說明、現場示範和 GitHub 上的示範程式碼。

後續步驟

我們希望與您一起討論，確保我們打造出適合所有人的 API。

討論 API

如同其他 Privacy Sandbox API，這個 API 會記錄並公開討論。

使用 API 進行實驗

您可以實驗並參與 Protected Audience API 的討論。