製作 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) {
  ...
}

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

auctionSignalsperBuyerSignals

傳遞給勝出出價方的 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 的对话。