製作 Protected Audience API 競價結果報表

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

本文提供技術參考資料，說明如何產生 Protected Audience API 競價勝出者的報表，如目前實驗性 Protected Audience API 版本中所使用。

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

如果您不是開發人員，請參閱 Protected Audience API API 總覽。

Protected Audience API 報表是什麼？

Protected Audience API 提供兩種報表：

  • 賣方報表：通知賣方競價勝出者。
  • 買方報表：只有得標買方才能參與競價，瞭解他們贏得競價。

長期計畫是讓瀏覽器透過 Private Aggregation API 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://flags/#privacy-sandbox-ads-apis，Chrome 預設可使用這些方法。不過，如果您在執行 Chrome 時使用指令列旗標來啟用 Protected Audience API，就必須加入 BiddingAndScoringDebugReportingAPI 標記來明確啟用這些方法。如果未啟用這個標記，方法仍然可用，但不會有任何作用。

所有 Protected Audience API 參考資料

可用的 API 參考指南如下：

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

後續步驟

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

討論 API

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

使用 API 進行實驗

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