Protected Audience API 競價報表

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

本文將概略說明您可向伺服器回報 Protected Audience API 競價資料的各種機制，以及目前您在遷移期間可使用的轉移機制。

如要記錄從廣告競價收集到的重要指標，Protected Audience API 可與：

• 私人匯總，會收集競價信號和結果以產生摘要報表。
• Fenced Frames 和 iframe 的 Ads Reporting API，是指頁框中的管道，可與 Protected Audience API 工作程式通訊。這個 API 可將事件層級資料與競價信號建立關聯。Ads Reporting API 的事件層級報表是過渡機制，直到系統設計出更私密的檢舉機制為止。
• 歸因報表：可讓您將轉換資料與競價信號建立關聯。
• 共用儲存空間：可讓您將競價信號寫入跨來源儲存空間，以便日後使用私人匯總功能記錄這些資料。

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 或 Fenced 頁框中的事件層級資料可與 Protected Audience API 競價資料建立關聯，並回報至您的伺服器。事件層級資料範例包括廣告曝光、點閱、懸停以及影格內發生的任何其他事件。

使用者在轉換期間，如果在歸因回競價的點閱頁面執行某些動作，轉換頁的事件層級資料就會與 Protected Audience API 競價資料建立關聯，並記錄到您的伺服器。

事件層級報表

事件層級報表提供一或多個事件的詳細資訊。事件可以是競價勝出、廣告曝光或轉換。至少在 2026 年前，事件層級的競價勝出報表將維持不變，不必設定圍欄頁框即可顯示 Protected Audience 廣告，而具備無限制網路存取權的 iframe 則可用於事件層級的報表。此外，Ads Reporting API 也位於圍欄頁框和 iframe 中，方便您將競價和轉換資料與影格中的事件層級資料建立關聯。這項設計的目的是為了讓生態系統有更簡便的遷移方式，因為在將系統遷移至 Protected Audience 期間，您可以繼續使用現有的報表基礎架構，直到 2026 年為止。

使用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 中的競價資料與事件層級資料建立關聯，但不重複 ID 則不適用於圍欄頁框，因為嵌入器和圍欄框架之間的通訊有限，因此無法從嵌入程式傳入。如要將競價資料與圍欄頁框廣告的事件層級資料建立關聯，可以使用 Ads Reporting API。

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

圍欄頁框和 iframe 的 Ads Reporting API 提供了一項機制，可讓您將廣告頁框中的使用者事件層級資料與 Protected Audience 競價的信號建立關聯。

在 Protected Audience API 報表研究室中，您可以使用 registerAdBeacon() 函式註冊廣告信標，並使用新增為查詢參數的信號傳入報表網址。此外，您也可以指定要與報表網址建立關聯的自訂事件。接著，等廣告於圍欄頁框中顯示時，您可以呼叫 window.fence.reportEvent() 函式來觸發自訂事件。Fenced 框架內可用的資料可以新增為酬載。

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 相同的方式載入網路資源，而且您可以將圍欄頁框中的事件層級資料傳送至伺服器。您之後可以在伺服器端產生事件層級報表，方法是將來自圍欄頁框的事件層級資料與透過 sendReportTo() 傳送的競價資料建立關聯 (如上方競價事件層級報表機制一節所述)。

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

歸因報表

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

在我們設計更永久的解決方案時，您可以使用適用於圍欄頁框的 Ads Reporting API，做為利用歸因報表產生事件層級報表和可匯總報表的過渡機制。請注意，這些報表用於評估轉換，與透過競價和廣告頁框產生的事件層級和可匯總參與度報表分開顯示。準備就緒後，我們會發布說明，介紹更永久性的解決方案。

轉換機制

註冊廣告信標時，您可以使用關鍵字 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']
})

詳情請參閱 Google Ads Reporting API 說明的「Attribution Reporting」一節。

參與度和轉換報表範例

在本例中，買方有意將競價、廣告頁框和轉換網站的資料建立關聯，我們會從這個角度來思考。

此工作流程中，買方會與賣方協調，以便傳送專屬 ID 參與競價。在競價期間，買方會透過競價資料傳送這個專屬 ID。在顯示和轉換期間，圍欄頁框或 iframe 的資料也會以相同的專屬 ID 送出。之後，專屬 ID 就能用來連結這些報表。

工作流程：

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

完成上述流程後，買方將取得競價報表、參與度報表和轉換報表，並以單一專屬鍵相互連結。

如果賣方需要存取歸因資料，則適用類似的工作流程，而賣方也可以使用以 registerAdBeacon() 傳送的專屬 ID。從頁框中，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 元，您可以將出價減去 NT $60 元，計算出實際贏得競價的金額，也就是 NT $90 元。

競價結果報表

讓我們先看看您在競價失敗的例子，瞭解自己出價與競價成交價格之間的差距。

如要瞭解在競價中落後的金額，您可以從得標出價減去出價價格：

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 API 可用的其中一個閘門是「私人匯總」。您只能從 Worklet 內部讀取共用儲存空間中的值，並使用工作程式中的 Private Aggregation 回報這些值。

您也可以透過 Protected Audience API 出價、評分和報表工具，寫入共用儲存空間。您稍後可以使用「私人匯總」功能，將共用儲存空間中的這些值回報至您的伺服器。您也可以在「網址選取」作業中使用已儲存的值。

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