Protected Audience API 競價報表

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

本文將概略介紹各種機制，方便您向伺服器回報 Protected Audience API 競價資料，並說明目前可用的轉換機制，讓您在遷移期間使用，直到替代解決方案準備就緒為止。

如要匯報從廣告競價收集的重要指標，Protected Audience API 可搭配下列項目使用：

• 私密匯總：收集競價信號和結果，產生摘要報表。
• 廣告報表 API，適用於 Fenced Frames 和 iframe，這是框架內的管道，可與 Protected Audience API 工作單通訊。API 可將事件層級資料與競價信號建立關聯。在設計出更注重隱私權的報表機制前，Google Ads 報表 API 的事件層級報表是過渡機制。
• 歸因報表：可將轉換資料與競價信號建立關聯。
• Shared Storage：可將競價信號寫入跨來源儲存空間，然後使用 Private Aggregation 稍後回報該資料。

Protected Audience API 報表總覽

在 Protected Audience API 競價流程中，有三個主要時間點可將資料回報給伺服器：競價時間 (從發布商網站執行競價時)、顯示時間 (廣告顯示在發布商網站的封閉架構或 iframe 中時)，以及轉換時間 (使用者在可歸因於競價的另一個網站上執行某些動作時)。

在競價期間，您可以使用報表工作集回報競價資料。在顯示期間，您可以從 iframe 或設限框架回報參與度資料。在轉換期間，您可以使用 Attribution Reporting API，從到達網頁回報歸因資料。

回報位置

在競價中，買方可以回報 generateBid() 和 reportWin() 工作集中的可用信號，賣方則可以回報 scoreAd() 和 reportResult() 中的可用信號。在競價以外，買方和賣方可以從顯示廣告的影格，以及轉換發生的網站回報資料。

在列出的每個時間範圍內，買方和賣方都可以使用各種報表 API，回報競價信號、事件層級資料和轉換資料等資料。

Protected Audience API 競價中可用的資料

在競價期間，您可以從 Protected Audience API 工作單回報下列資料。

信號

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

競價設定物件是提供資料的主要來源，這些資料會成為工作單中的信號。發布商和賣方可以在競價設定中提供內容資料和第一方資料，這些信號可以透過買方的興趣群組資料、廣告顯示影格的事件層級資料，以及點擊後到達網頁的歸因資料進行擴充。您可以使用這些資料製作買家/賣家報表、結算帳單、編列預算，以及訓練機器學習模型等。

其他可用的資料

• 與競價勝出和落敗資料相關的結果資料，例如勝出出價價格和出價遭拒原因。
• 成效資料，包含延遲時間資訊，例如擷取及執行出價工作單所花費的時間。

Protected Audience API 競價以外的可用資料

在 Protected Audience API 競價以外，有兩個時間範圍可供製作資料報表。

在顯示期間，當廣告顯示在發布商網站上時，系統會將 iframe 或設有圍欄的影格內的事件層級資料，與 Protected Audience API 競價資料建立關聯，並向您的伺服器回報。事件層級資料範例包括廣告曝光、點閱、懸停，以及影格內發生的任何其他事件。

在轉換期間，如果使用者在歸因於競價的點擊後網頁上執行某些動作，轉換網頁的事件層級資料就會與 Protected Audience API 競價資料建立關聯，並回報給您的伺服器。

事件層級報表

事件層級報表會詳細列出一個或多個事件的資訊。事件可以是贏得競價、廣告曝光或轉換。至少在 2026 年之前，系統仍會提供事件層級的競價得標報表，且不必使用設有範圍的框架即可算繪 Protected Audience 廣告，並可使用網路存取不受限制的 iframe 進行事件層級報表。此外，您也可以在設有安全防護的框架和 iframe 中使用 Ads Reporting API，將競價和轉換資料與框架中的事件層級資料建立關聯。這項設計可讓生態系統更輕鬆地完成遷移，因為您至少可以繼續使用現有的報表基礎架構到 2026 年，同時將系統遷移至 Protected Audience。

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

在 Protected Audience 競價中，sendReportTo() function 是用來回報事件層級資料的機制，會在競價勝出時觸發。買方和賣方報表工作集都提供這項函式，且瀏覽器會在廣告開始算繪時，向提供的網址字串發出 GET 要求。您可以將工作區中提供的任何信號編碼為網址的查詢參數。

舉例來說，買方可以從 reportWin() worklet 回報得標出價金額，以利帳單作業：

// 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 中的事件層級資料建立關聯，但由於嵌入器與設有安全防護的框架之間的通訊受到限制，因此無法從嵌入器傳遞專屬 ID，這個函式不適用於設有安全防護的框架。如要將競價資料與來自設有圍欄的影格廣告的事件層級資料建立關聯，可以使用 Ads Reporting API。

適用於 Fenced Frame 和 iframe 的 Ads Reporting API

適用於設有圍欄的影格和 iframe 的 廣告報表 API 提供機制，可讓您將廣告影格中的使用者事件層級資料，與 Protected Audience 競價中的信號建立關聯。

在 Protected Audience API 報表工作單中，您可以使用 registerAdBeacon() 函式註冊廣告信標，並傳遞報表網址，其中信號會以查詢參數的形式加入。您也可以指定要與報表網址建立關聯的自訂事件。然後，當廣告稍後在設有圍欄的影格中顯示時，您可以呼叫 window.fence.reportEvent() 函式來觸發自訂事件。您可以將圍欄框架內可用的資料新增為酬載。

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 年。

如要深入瞭解，請參閱說明。

不受限制的網路存取權

封鎖框架可載入網路資源，方式與 iframe 相同，您也可以在封鎖框架內將事件層級資料傳送至伺服器。您稍後可以在伺服器端產生事件層級報表，方法是將來自設有安全防護的影格的事件層級資料，與透過 sendReportTo() 傳送的競價資料建立關聯，如上文「競價事件層級報表機制」一節所述。

日後網路存取權將受到限制。

歸因報表

歸因報表可讓您將網站上的轉換與從 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。而在顯示和轉換期間，受限框架或 iframe 的資料也會以相同的專屬 ID 送出。之後，專屬 ID 就能用來建立這些報表的關聯。

工作流程：

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

完成上述流程後，買方將取得競價報表、參與度報表和轉換報表，這些報表都透過單一專屬金鑰建立關聯。

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

匯總 Protected Audience 資料

Private Aggregation API 是用來回報 Protected Audience 資料的機制，可產生摘要報表，這類報表會匯總值區中收集的資料，並加入隨機雜訊。儲存區以匯總鍵表示，部分資訊可編碼至該鍵。

舉例來說，廣告曝光事件可以計入不同儲存區，每個儲存區代表不同的廣告活動。摘要報表與事件層級報表不同，不會揭露個別事件的資訊。透過事件層級報表，您可以判斷使用者 A、B 和 C 看過廣告活動 123。摘要報表會顯示看過廣告活動 123 的使用者人數，並加入雜訊來保護使用者隱私。

如要進一步瞭解這項 API，請參閱「Private Aggregation」一文。

匯總競價信號

您可以使用私密匯總，將工作單元中可用的信號匯總至伺服器。如要匯總信號，可以使用買方出價工作小程式、賣方評分工作小程式，以及買方/賣方報表工作小程式中提供的 privateAggregation.contributeToHistogram() 方法。

在本範例中，勝出的出價會匯總至興趣群組擁有者儲存區：

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

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

如果想匯總的信號與事件層級資料無關，且不是由競價以外的事件觸發，請使用這項一般機制。如要進一步瞭解如何回報競價信號，請參閱說明。

匯總競價信號與事件資料

您可以匯總競價信號，但只能取得廣告影格中發生的事件相關資訊。舉例來說，您可以建立代表廣告活動和點擊事件的 bucket，集中評估廣告活動的廣告獲得多少點擊次數。請注意，您可以在廣告影格中指定發生的事件，但無法附加事件層級的酬載。

如要依事件匯總競價信號，可以使用 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)，觸發檢舉提交程序：

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

競價結果和成效報表

您也可以在因競價勝出或落敗事件觸發時，使用 contributeToHistogramOnEvent(eventType, contribution) 匯總競價結果，方法是傳遞保留的事件類型關鍵字 (reserved.win, reserved.loss 和 reserved.always)。

私密匯總會提供基本值清單，您可從中計算出貢獻的 bucket 和值。競價結果可用的基本值包括：得標廣告的出價值、評為次高的出價值，以及出價遭競價拒絕的原因。

如果提供一些基本值 (例如得標出價金額)，您可以設定要從該值加減多少，然後回報最終值。舉例來說，如果系統提供 $5 美元的得標出價做為基準值，您可以減去 $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 
    }
  });
}

提交報表後，實際回報值會是經過縮放的 baseValue，並依 offset 值位移。詳情請參閱說明。

成效報表

買方和賣方可以回報指令碼的執行時間，以及擷取信任訊號的時間。賣方可取得各買方的出價產生時間和可信出價信號時間 (須經買方同意)。

詳情請參閱說明。

在 Shared Storage 中儲存競價信號

共用儲存空間是未經分割的跨來源儲存空間，您可以自由寫入資料，但讀取及處理儲存的值時，會受到閘道保護。Private Aggregation 是 Shared Storage API 的可用閘道之一。您只能從工作單元內部讀取共用儲存空間中的值，並從工作單元使用私有匯總功能回報這些值。

您也可以從 Protected Audience API 出價、評分和報表工作集寫入共用儲存空間。之後，您可以使用 Private Aggregation，將共用儲存空間中的這些值回報給伺服器。您也可以將儲存的值用於「網址選取」作業。

您可以從 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 的討論。