Protected Audience API オークション結果のレポート

この記事は、実験的な Protected Audience API の現在のイテレーションで使用される、Protected Audience API オークションの落札に関するレポートを生成するための技術リファレンスです。

Protected Audience API のライフサイクル全体については開発者ガイドを参照し、イベント レベルのレポート（暫定）の詳細なディスカッションについては Protected Audience API の Explainer をご覧ください。

開発者でない方は、Protected Audience API の API の概要をご覧ください。

# Protected Audience API がレポートする内容

Protected Audience API レポートには 2 種類あります。

• 売り手レポート: 広告オークションの落札者を売り手に通知します。
• 買い手レポート: 落札した買い手のみが利用でき、オークションで落札したことを知ることができます。

長期的には、Private Aggreagation API を使用して、ブラウザが売り手と買い手のオークション結果をレポートできるようにすることを計画しています。暫定的なイベントレベルのレポートの仕組みとして、売り手用に reportResult() を実装し、落札者用に reportWin() を実装するコードは、sendReportTo() 関数を呼び出すことができます。これはオークションの完了後に取得される URL を表す文字列を引数として取ります。これにより、レポートされるイベントレベルの情報が暗号化されます。

# 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 では、暫定的に 2 つの方法でオークションの勝敗をレポートできます。

• forDebuggingOnly.reportAdAuctionLoss()
• forDebuggingOnly.reportAdAuctionWin()

これらのメソッドはそれぞれ、オークションの完了後に取得する URL を引数として取ります。scoreAd() と generateBid() の両方で、異なる URL 引数を使用して何度も呼び出すことができます。

Chrome は、オークションが完了するまで実行された場合にのみ、デバッグの勝敗レポートを送信します。オークションがキャンセルされた場合（新しいナビゲーションなどが原因で）、レポートは生成されません。

これらのメソッドは、Chrome で chrome://flags/#privacy-sandbox-ads-apis が有効になっている場合にデフォルトで使用できます。ただし、Protected Audience API を有効にするコマンドライン フラグを使用して Chrome を実行している場合は、BiddingAndScoringDebugReportingAPI フラグを含めて、メソッドを明示的に有効にする必要があります。フラグが有効になっていない場合、メソッドは引き続き使用できますが、何も起こりません。

# すべての Protected Audience API リファレンス

以下の API リファレンスガイドが提供されています。

• Protected Audience API の開発者ガイド。
• Protected Audience インタレストグループと入札生成に関する広告バイヤーガイド。
• Protected Audience 広告オークションに関する広告セラーガイド。
• オークション結果のレポートに関するガイド
• Protected Audience 広告オークションのレイテンシに関するベストプラクティス
• Protected Audience のトラブルシューティング

Protected Audience API の Explainer には、機能のサポートと制約に関する詳細が提供されています。

# 今後の予定

すべての人にとって機能する API を確実に構築できるように、皆さんとの対話を持ちたいと考えています。

# この API に関するディスカッション

他のプライバシーサンドボックス提案と同様に、この API は文書化され、公に議論されています。

# API の実験

Protected Audience API を試して会話に参加できます。