パブリッシャーのページで広告オークションを設定する

Protected Audience API オークションを構成する方法について説明します。

販売者によるオンデバイスオークション

デバイス上の Protected Audience オークションは、広告スペースを販売するサイトで実行されます。オークションを実行する当事者を販売者と呼びます。多くの関係者が販売者として行動する可能性があります。サイトが独自の広告オークションを実施したり、第三者のスクリプトを含めてオークションを実施したり、デバイス上のオークションの実施と他のサーバーサイドの広告オークションアクティビティを組み合わせた SSP を使用したりする可能性があります。オンデバイス広告オークションでは、販売者は次の 3 つの基本的な役割を担います。

販売者は、（a）どの購入者が参加できるか、（b）それらの購入者のインタレストグループからのどの入札がオークションに参加できるかを決定します。これにより、販売者はページに表示できる広告に関するサイトのルールを適用できます。
販売者はオークションのビジネスロジック（各入札の価格とメタデータを考慮して「望ましさ」のスコアを計算する JavaScript コード）を担当します。望ましさスコアが最も高い入札がオークションで落札されます。
販売者は、落札価格やその他の支払いに関する情報など、オークションの結果に関するレポートを作成します。落札した購入者と落札できなかった購入者も、独自のレポートを作成できます。

このドキュメントでは、オンデバイスオークションを構成して開始する方法について説明します。

Protected Audience API 広告オークションを構成する

Protected Audience API の広告オークションを実施するには、まずオークションを構成します。これを行うには、auctionConfig オブジェクトを作成します。このような構成の例を次に示します。

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

`AuctionConfig` 件の宿泊施設

必須プロパティ

auctionConfigs の必須プロパティは、seller、decisionLogicUrl、interestGroupBuyers のみです。

プロパティ	例	ロール
seller	https://seller.example	販売者のオリジン。
decisionLogicUrl	https://seller.example/decision-logic.js	オークションの JavaScript 判断ロジックワークレットの URL。このフィールドは、販売者フィールドと同じオリジンを持つ必要があります。
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	オークションで入札を求められたすべてのインタレストグループオーナーのオリジン

省略可能なプロパティ

auctionConfigs の残りのプロパティは省略可能です。

プロパティ	例	ロール
trustedScoringSignalsUrl	https://seller.example/scoring-signals	販売者の Key/Value サーバーの URL。これは、クリエイティブのレンダリング URL をキーとして使用して、広告のスコアリングプロセス中にクエリされます。このフィールドは、販売者フィールドと同じオリジンを持つ必要があります。
auctionSignals	{"category":"news"}	オークションに参加するすべての購入者と販売者が利用できるシグナルを表す、JSON シリアル化可能なオブジェクト。
sellerSignals	{...}	販売者のみが利用できるシグナルを表す、JSON シリアル化可能なオブジェクト。
perBuyerSignals	{https://dsp.example: {...}, https://another-buyer.example: {...}, ... }	特定の購入者が利用できるシグナル。シグナルは販売者から提供されることもあれば、購入者自身から提供されることもあります。
perBuyerTimeouts	{https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...},	特定の購入者の generateBid() スクリプトの最大実行時間（ミリ秒単位）。ワイルドカード記号は、特定のタイムアウトが定義されていないすべてのバイヤーに適用されます。
sellerTimeout	100	販売者の scoreAd() スクリプトの最大実行時間（ミリ秒）。
componentAuctions	[{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...]	コンポーネントオークションの追加構成。
resolveToConfig	true\|false	runAdAuction() から返された Promise を、true の場合は FencedFrameConfig（<fencedframe> で使用）、false の場合は不透明な urn:uuid URL（<iframe> で使用）に解決するよう指示するブール値。デフォルトは false です。

非同期でシグナルを提供する

一部のシグナルの値（auctionSignals、sellerSignals、perBuyerSignals、perBuyerTimeouts フィールドで構成されたもの）は、具体的な値ではなく、Promise として提供することもできます。これにより、スクリプトや信頼できるシグナルの読み込み、分離されたワークレットプロセスの起動など、オークションの一部で、これらの値の計算（またはネットワーク取得）を重複させることができます。ワークレットスクリプトには解決済みの値のみが表示されます。このような Promise が拒否された場合、オークションはすでに失敗したか、他の方法で中止された場合を除き、中止されます。

複数の販売者でオークションを設定する

複数の販売者がオークションに参加し、別の販売者が実施する別のオークションに、個別のオークションの落札者が渡される場合があります。これらの個別のオークションが渡されることを、コンポーネントオークションと呼びます。これらのコンポーネントオークションを容易にするため、componentAuctions オブジェクトには、販売者のコンポーネントオークションごとにオークション構成を追加できます。これらのコンポーネントオークションの落札単価は、オークションの最終決定を行う「トップレベル」オークションに渡されます。コンポーネントオークションの auctionConfig には、独自の componentAuctions がない場合があります。componentAuctions が空でない場合、interestGroupBuyers は空である必要があります。つまり、特定の保護されたオーディエンスオークションでは、単一の販売者が存在し、コンポーネントオークションが存在しないか、すべての入札がコンポーネントオークションから行われ、トップレベルのオークションはコンポーネントオークションの落札者の中からのみ選択できます。

オークションを実施する

販売者は、navigator.runAdAuction() を呼び出して広告オークションを開始するようユーザーのブラウザにリクエストします。

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() 呼び出しは、広告に解決される Promise を返します。パブリッシャーページのコードが、runAdAuction() の結果から落札広告を検査したり、その内容を把握したりすることはできません。AuctionConfig で resolveToConfig フラグが true に設定されている場合、フェンス付きフレームでのみレンダリングできる FencedFrameConfig オブジェクトが返されます。フラグが false に設定されている場合は、iframe でレンダリングできる不透明な URN が返されます。runAdAuction が null 値を返す可能性もあります。これは、広告が選択されなかったことを示します。この場合、販売者はコンテキストターゲット広告のレンダリングを選択できます。