このページは Cloud Translation API によって翻訳されました。

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

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

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

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

Protected Audience API の広告オークションの 6 つの段階 — この図は、Protected Audience API の広告オークションの各ステージの概要を示しています。

ユーザーが広告を表示するサイトにアクセスします。
販売者のコードが 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() を使用して、サーバーに報告します。