1 人の販売者によるブラウザベースのオークションを実施する

このドキュメントでは、Protected Audience API の現在のイテレーションを使用した、単一の販売者の Protected Audience データを使用してオークションを実行する方法の概要について説明します。単一の販売者によるオークションは、複数の販売者を巻き込んだより複雑なオークションの一部として実行できます。この場合、単一販売者のオークションは「コンポーネントオークション」と呼ばれ、複数の販売者が参加する「最上位オークション」に広告候補を提供できます。

Protected Audience API のライフサイクル全体については、デベロッパーガイドをご覧ください。販売者がデバイス上のオークションを実施する方法について詳しくは、Protected Audience API の説明をご覧ください。

Protected Audience API 広告オークションの 6 つのステージ

ユーザーが広告を表示するサイトにアクセスします。
販売者のコードが navigator.runAdAuction() を実行します。これにより、販売対象の広告枠と入札できるユーザーを指定します。販売者は、各入札にスコアを付けるスクリプト（scoreAd()）も含める必要があります。
招待された購入者のコードが実行され、入札単価、関連する広告クリエイティブの URL などのデータが生成されます。入札スクリプトは、購入者の Key-Value サービスから、広告キャンペーンの残りの予算などのリアルタイムデータをクエリできます。
販売者のコードは、各入札単価をスコアリングして落札者を選択します。このロジックは、入札単価の値とその他のデータを使用して、入札の優先度を返します。コンテキストウィナーに勝てない広告は拒否されます。販売者は、リアルタイムデータに独自の Key-Value サービスを使用できます。
落札広告は不透明な値として返され、フェンス付きフレームに表示されます。販売者とパブリッシャーの両方がこの値を表示することはできません。
オークションは、販売者と落札した購入者に報告されます。

オークションは、ユーザーが広告が表示されるページに移動したときに行われます。広告スロットが表示されるときに広告クリエイティブが準備できるように、オークションが事前に実行される場合があります。

販売者は広告オークションを開始し、scoreAd() 関数として提供されるカスタムロジックを使用して広告候補をスコアリングします。また、オークションの結果を自分自身と落札した購入者に報告する責任があります。販売者は、scoreAd() 関数を使用してパブリッシャーのルールを適用し、広告の品質をフィルタすることもできます。

販売者は次のことを参照している可能性があります。

コンテンツパブリッシャー（自社でウェブサイトに広告コンテンツをホストする）
サプライサイドプラットフォーム（SSP）: 広告パブリッシャーと連携してその他のサービスを提供
パブリッシャーに代わって広告オークションへの参加を可能にするサードパーティスクリプト。

オークションを実施するための前提条件

オークションを実行するには、販売者が次の 2 つの JavaScript 関数を定義する必要があります。

scoreAd(): 広告候補のスコア
reportResult(): オークションの結果を販売者に報告します。

これらのスクリプトは、販売者が所有する単一のエンドポイントから提供する必要があります。

`scoreAd()`

販売者は、所有するエンドポイントから提供される scoreAd() 関数を定義する必要があります。エンドポイントは、オークション構成で decisionLogicUrl として指定します。scoreAd() 関数のシグネチャは次のとおりです。

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

scoreAd() パラメータは次のとおりです。

adMetaData: 購入者から提供された広告クリエイティブに関する任意のメタデータ。これは JSON シリアル化可能なオブジェクトであり、販売者と購入者が構造を定義して合意する必要があります。
bid: 入札単価を表す数値。
auctionConfig: オークションの実行に使用されるオークション構成。
trustedScoringSignals: オークション時に販売者のKey/Value サーバーから読み取られるシグナル。プラットフォームでは、このルックアップのキーとして候補広告の renderUrl が使用されます。
browserSignals: ブラウザによって作成されるオブジェクト。ブラウザが認識し、販売者のオークションスクリプトが検証する必要がある情報が含まれます。
directFromSellerSignals は、次のフィールドを含むオブジェクトです。** sellerSignals: auctionConfig.sellerSignals と同様ですが、directFromSellerSignals メカニズムを使用して渡されます。** auctionSignals: auctionConfig.auctionSignals に似ていますが、directFromSellerSignals メカニズムを使用して渡されます。

browserSignals の例を次に示します。候補広告の renderUrl は、次のシグナルで取得できます。

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

`reportResult()`

販売者は、所有するエンドポイントから提供される reportResult() 関数を定義する必要があります。エンドポイントは、オークション構成で decisionLogicUrl として指定します。reportResult() 関数のシグネチャは次のとおりです。

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

reportResult() パラメータは次のとおりです。

auctionConfig: オークションの実行に使用されるオークション構成。
browserSignals: ブラウザによって作成されるオブジェクト。ブラウザが認識し、販売者のオークションスクリプトが検証する必要がある情報が含まれます。これは、scoreAds() 関数に渡されるオブジェクトと同じです。

reportResult() は signalsForWinner を返します。これは、落札した購入者のレポート関数に渡される任意の JSON オブジェクトです。これには、購入者のレポートに必要なオークションに関する関連情報を販売者が提供できる必要があります。

Protected Audience API オークションを実施する

販売者がオークションを実施するには、主に次の 4 つのステップが必要です。なお、これらの手順では、このガイドで前述した必要な JavaScript を返すエンドポイントが販売者に設定されていることを前提としています。

オークションを構成します。このステップには、auctionConfig オブジェクトの作成が含まれます。これにより、販売者はオークションに参加する購入者を指定するだけでなく、入札の生成や広告のスコアリングに関連するシグナルを提供できます。
navigator.runAdAuction() を呼び出して、前の手順で作成した構成を渡し、オークションを実行します。これにより、購入者が入札を生成してスコアリングするチェーンが開始されます。このステップの最終的な結果は、レンダリングして広告を表示できる広告候補です。
フェンス付きフレームまたは iframe に落札広告をレンダリングします。
オークションの結果を報告します。レポートを開始する関数 navigator.sendReportTo() があります。販売者は常にオークションの結果のレポートを受け取ります。レポートを受け取るのは、オークションで落札した購入者のみです。この場合、このガイドの前半で説明した販売者の reportResult() を使用してサーバーに報告します。

1 人の販売者によるブラウザベースのオークションを実施する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。