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 を使用して販売者と購入者のオークション結果をレポートできるようにします。一時的なイベントレベルのレポート メカニズムとして、販売者向けの reportResult() と落札者向けの reportWin() を実装するコードは、sendReportTo() 関数を呼び出すことができます。この関数は、オークションの完了後にフェッチされる URL を表す文字列を 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）を取ります。scoreAd() と generateBid() の両方で、異なる URL 引数を使用して複数回呼び出すことができます。

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

これらのメソッドは、chrome://settings/adPrivacy で Ad Privacy API をすべて有効にすると、Chrome でデフォルトで使用できるようになります。コマンドライン フラグを使用して Protected Audience API を有効にして Chrome を実行している場合は、BiddingAndScoringDebugReportingAPI フラグを含めてメソッドを明示的に有効にする必要があります。フラグが有効になっていない場合でも、メソッドは使用できますが、何も行いません。

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

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

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

次のステップ

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

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

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

API を試す

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