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

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

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