製作 Protected Audience API 競價結果報表

賣家和買家指南：產生 Protected Audience API 競價報表。

本文是技術參考資料，說明如何產生 Protected Audience API 競價勝出的報表，適用於目前實驗性 Protected Audience API 的疊代版本。

請參閱開發人員指南，瞭解 Protected Audience API 的完整生命週期，並參閱 Protected Audience API 說明，深入瞭解事件層級報表 (暫時)。

不是開發人員嗎？請參閱 Protected Audience API 總覽。

Protected Audience API 會回報哪些內容？

系統提供下列兩種 Protected Audience API 報表：

  • 賣方報表：通知賣方廣告競價得主。
  • 買家報表：只有得標買家才能查看，瞭解自己贏得競價。

我們的長期計畫是希望讓瀏覽器透過 Private Aggregation API，向賣家和買家回報競價結果。做為暫時的事件層級報表機制，實作 reportResult() (賣方) 和 reportWin() (得標出價者) 的程式碼可以呼叫 sendReportTo() 函式。這項函式會採用單一引數：代表競價完成後擷取網址的字串，其中會編碼要回報的事件層級資訊。

API 函式

賣方：reportResult()

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 引數。

買家：reportWin()

得標出價者的 JavaScript (也提供 generateBid()) 可以包含 reportWin() 函式，用來回報競價結果。

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

傳遞至這個函式的引數如下：

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://settings/adPrivacy 下啟用所有廣告隱私權 API 後，Chrome 預設會提供這些方法。如果您使用指令列旗標執行 Chrome，以啟用 Protected Audience API，則必須加入 BiddingAndScoringDebugReportingAPI 旗標，明確啟用這些方法。如果未啟用這個標記，這些方法仍可使用，但不會執行任何動作。

所有 Protected Audience API API 參照

可用的 API 參考指南如下：

Protected Audience API 說明也提供功能支援和限制的詳細資料。

後續步驟

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

討論 API

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

使用 API 進行實驗

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