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 レポートは 2 つあります。

  • 販売者レポート: 広告オークションで落札されたことを販売者に通知します。
  • 購入者レポート: 落札した購入者が、オークションで落札したことを確認できます。

長期計画では、Private Aggregation API API を使用して、ブラウザから販売者と購入者のオークション結果を報告できるようにします。一時的なイベントレベルのレポート メカニズムとして、販売者の reportResult() と落札ビッダーの reportWin() を実装するコードは、sendReportTo() 関数を呼び出すことができます。ここでとる引数は 1 つだけです。これは、オークションの完了後に取得される 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()

これらの各メソッドは、1 つの引数（オークションの完了後に取得する URL）を取ります。異なる URL 引数を指定して、scoreAd() と generateBid() の両方で複数回呼び出すことができます。

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

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

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

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

Protected Audience API の解説では、機能のサポートと制約に関する詳細も説明しています。

次のステップ

誰もが利用できる API を構築するために、Google は皆様との対話を通じてしたいと考えています。

API についてディスカッションする

他のプライバシー サンドボックス API と同様に、この API はドキュメント化され、一般公開されているです。

API を試す

Protected Audience API に関する会話をテストして参加できます。