Protected Audience API 競價報表

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

如要回報從廣告競價中收集到的重點指標，Protected Audience API 可搭配以下項目：

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

Protected Audience API 報表總覽

有三個主要時間點，Protected Audience API 競價流程的資料可回報至伺服器：競價時間 (從發布商網站執行競價)、轉換時間 (廣告在發布商網站上轉換為受保護的框架或 iframe)，以及轉換時間 (使用者在另一個網站上執行可歸因於競價的動作)。

在競價期間，您可以使用報表工作區回報競價資料。在轉譯期間，您可以從 iframe 或 fenced frame 回報參與資料。在轉換期間，您可以使用 Attribution Reporting API 回報到達網頁的歸因資料。

回報位置

在競價中，買方可回報 generateBid() 和 reportWin() 工作區塊中提供的信號，賣方則可回報 scoreAd() 和 reportResult() 中提供的信號。在競價之外，買方和賣方可以回報廣告顯示框和轉換網站的資料。

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

Protected Audience API 競價中提供的資料

競價期間，Protected Audience API 工作區塊可回報下列資料。

信號

信號是指工作區塊內買方和賣方可用的競價內容資料、使用者資料、即時資料和瀏覽器資料，可用於產生出價、評估廣告，以及回報競價結果。

auction config 物件是主要資料來源，可在 worklet 中做為信號使用。發布商和賣方可以在競價設定中提供比對內容資料和第一方資料，這些信號可透過買方提供的興趣群組資料、廣告轉譯框架提供的事件層級資料，以及點閱頁面提供的歸因資料加以強化。回報的資料可用於買方/賣方報表、帳單、預算、機器學習模型訓練等。

其他可用資料

• 與競價勝出和失敗相關的結果資料，例如勝出出價價格和出價遭拒原因。
• 效能資料：包含延遲時間資訊，例如擷取及執行出價工作區塊所需的時間。

可在 Protected Audience API 競價外取得的資料

除了 Protected Audience API 競價外，還有兩個時間範圍可回報資料。

在顯示期間，廣告在發布商網站上顯示時，iframe 或區隔框架內的事件層級資料可與 Protected Audience API 競價資料建立關聯，並回報至伺服器。事件層級資料的範例包括廣告曝光、點擊率、滑鼠游標，以及在廣告框內發生的任何其他事件。

在轉換期間，如果使用者在點閱頁面上採取某些動作，且這些動作可歸因於競價，轉換頁面中的事件層級資料就能與 Protected Audience API 競價資料建立關聯，並回報給您的伺服器。

事件層級報表

事件層級報表會提供一或多個事件的詳細資訊。事件可以是競價勝出、廣告曝光或轉換。至少在 2026 年前，事件層級競價勝出報表仍會保留，且不必使用柵欄框架來顯示 Protected Audience 廣告，而且可以使用未受限的網路存取權 iframe 進行事件層級報表。此外，廣告報表 API 也適用於封閉式框架和 iframe，可將競價和轉換資料與框架中的事件層級資料建立關聯。這項功能旨在讓生態系統更容易遷移，因為您至少可在 2026 年前繼續使用現有的報表基礎架構，同時將系統遷移至 Protected Audience。

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

在目標對象受保護競價中，您可以透過競價勝出事件的 sendReportTo() function，記錄事件層級資料。這個函式可用於買方和賣方的報表工作區，瀏覽器會在廣告轉譯開始時對所提供的網址字串提出 GET 要求。您可以將工作區塊中可用的任何信號，編碼為網址的查詢參數。

舉例來說，買方可以針對帳單目的，回報 reportWin() 工作區塊中的得標出價金額：

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

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

「參與」報表

參與度報表包含廣告素材資源的事件層級資料，例如曝光或點擊資料，這些資料與呈現廣告的 Protected Audience API 競價的信號相關。由於廣告是在競價結束後算繪，因此在算繪廣告的框架中無法使用競價信號。為了將不同時間範圍的資料連結在一起，我們提供兩種轉換機制，以便產生參與度報表。

如上所述，sendReportTo() 函式可用於將競價資料與 iframe 中的事件層級資料建立關聯，但不適用於受限的框架，因為嵌入程式與受限框架之間的通訊受到限制，因此無法從嵌入程式傳入專屬 ID。如要將競價資料與受保護廣告框廣告的事件層級資料建立關聯，可以使用 Google Ads Reporting API。

適用於 Fenced Frames 和 iframe 的 Google Ads Reporting API

針對受限框架和 iframe 的 Ads Reporting 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 的封閉區塊，作為產生事件層級和可匯總報表的過渡機制，以便使用歸因報表。請注意，這些報表是用於評估轉換，與從競價和廣告框產生的事件層級和可匯總參與度報表不同。我們會在準備就緒時，發布更永久的解決方案說明。

過渡機制

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

詳情請參閱 廣告報表 API 說明的「歸因報表」一節。

參與度和轉換報表範例

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

在這個工作流程中，買方會與賣方協調，以便傳送專屬 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)
  });
} 

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

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

您可以匯總競價信號，並利用廣告框中發生事件的有限資訊。舉例來說，您可以建立代表廣告活動和點擊事件的資料欄，以便匯總評估廣告活動廣告獲得的點擊次數。請注意，您可以在廣告框中指定發生的事件，但無法附加事件層級酬載。

如要依事件匯總競價信號，您可以使用 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) 透過競價勝出或失敗事件觸發競價結果匯總。

私人匯總功能會提供一組基本值清單，您可以根據這份清單計算出貢獻值和值的值區。競價結果可用的基礎值包括得標廣告的出價價值、評為次高分的出價價值，以及出價遭競價拒絕的原因。

當您提供某些基本值 (例如得標出價金額) 時，可以設定要從該值加減多少，然後回報最終值。舉例來說，如果勝出出價的基礎值為 $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 
    }
  });
}

提交報表後，實際回報值會是經過 offset 值調整的 baseValue 值。詳情請參閱說明文章。

成效報表

買方和賣方可以回報指令碼執行所需的時間，以及擷取信任信號所需的時間。賣方可以收集每位買方的出價產生時間和信任出價信號時間 (須取得對方同意)。

詳情請參閱說明文章。

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

共用儲存空間是未分割的跨來源儲存空間，您可以自由寫入，但在讀取及處理儲存的值時，會受到閘門保護。Private Aggregation 是 Shared Storage API 可用的其中一個閘門。您只能從工作模組中讀取共用儲存空間中的值，並使用工作模組中的私人匯總功能回報這些值。

您也可以透過 Protected Audience API 出價、評分和報表工作片段，將資料寫入 Shared Storage。之後，您可以使用 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);

如要進一步瞭解 Shared Storage，請參閱 Protected Audience API 報表開發人員指南的 Shared Storage 專區、說明影片、即時示範，以及 GitHub 上的示範程式碼。

後續步驟

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

討論 API

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

使用 API 進行實驗

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