販売者向けガイド: 広告オークションの実施

Protected Audience API 広告オークションの販売者 API ガイドとリファレンス。

この記事では、試験運用版の Protected Audience API の現在のイテレーションで使用されている広告オークションの技術的なリファレンスについて説明します。

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

デベロッパーでない場合Protected Audience API の概要を参照してください。

Protected Audience API の広告オークションとは

Protected Audience API の広告オークションは、ブラウザがユーザーのデバイスで実行して広告を選択する小さな JavaScript プログラムの集まりです。プライバシーを保護するため、販売者と購入者のすべての広告オークション コードは、外部と通信できない分離された JavaScript ワークレットで実行されます。

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

オークションはいつ開催されますか？

Protected Audience API は、単独で実行することも、プログラマティック オークションと組み合わせて実行することもできます。マルチセラーのプログラマティック オークションの場合:

  1. ユーザーが参加サイトにアクセスします。
  2. 別の販売者がプログラマティック オークションを実施して、利用可能な広告スロットのコンテキスト広告を見つけます。
  3. Protected Audience API オークションが実行されます。
  4. scoreAd() は、購入者の入札単価を最初のオークションの結果と比較します。

コンテキストの勝者に勝てない入札は拒否されます。

Protected Audience API の広告オークションは誰が実施しますか？

広告スペースを販売するためにオークションを実施する複数の当事者が存在します。

次に例を示します。

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

Protected Audience API では、販売者は次の 3 つのジョブを実行します。

  • パブリッシャー ルールを適用する: どの購入者とどの入札が対象となるか。
  • オークション ロジックの実行: ワークレットで実行される JavaScript。各入札の望ましさスコアを計算します。
  • オークションの結果を報告します。

これらのジョブは、販売者が JavaScript 関数 navigator.runAdAuction() を呼び出して広告オークションを開始するときに提供するコードで、プログラムによって実行されます。

API 関数

runAdAuction()

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

次に例を示します。

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

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

runAdAuction() は、広告オークションの結果を表す URN（urn:uuid:<something>）に解決される Promise を返します。これは、レンダリングのためにフェンス付きフレームに渡された場合にのみブラウザでデコードできます。パブリッシャーのページで落札した広告を検査することはできません。

decisionLogicUrl スクリプトは、関連する入札単価とメタデータとともに、個々の広告を 1 つずつ考慮し、望ましさの数値スコアを割り当てます。

auctionConfig 件の宿泊施設

seller
必須
例: 'https://ssp.example'
役割: 販売者の出身地。
decisionLogicUrl
必須
例: 'https://ssp.example/auction-decision-logic.js'
役割: オークション ワークレット JavaScript の URL。
trustedScoringSignalsUrl
省略可
例: 'https://ssp.example/scoring-signals'
役割: 販売者の信頼できるサーバーの URL。
interestGroupBuyers
必須
例: ['https://dsp.example', 'https://buyer2.example', ...]
役割: オークションで入札を求められたすべてのインタレスト グループ オーナーのオリジン。
注: 販売者は、すべてのインタレスト グループに入札を許可するために interestGroupBuyers: を指定できます。広告は、インタレスト グループの所有者の追加以外の基準に基づいて承認または不承認となります。たとえば、販売者は広告クリエイティブを審査して、自社のポリシーに準拠しているかどうかを確認できます。
auctionSignals
省略可
例: {...}
役割: ページ コンテキスト、オークションの種類などに関する販売者情報
sellerSignals
省略可
例: {...}
役割: パブリッシャーの設定に基づく情報。コンテキスト広告リクエストなどの作成。
sellerTimeout
省略可
例: 100
役割: 販売者の scoreAd() スクリプトの最大実行時間（ミリ秒）。
perBuyerSignals
省略可
例: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
役割: 各特定の購入者のサーバーから取得した、ページに関するコンテキスト シグナル。
perBuyerTimeouts
省略可
例: 50
役割: 特定の購入者の generateBid() スクリプトの最大実行時間（ミリ秒）。
componentAuctions
省略可
例: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
役割: コンポーネント オークションの追加構成。



decisionLogicUrl

decisionLogicUrl はオークション構成オブジェクトのプロパティで、runAdAuction() に渡されます。この URL には、scoreAd() 関数のスクリプトを含める必要があります。このロジックは、各広告の望ましさを判断するために 1 回実行されます。

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals はブラウザによって作成されたオブジェクトで、ブラウザが認識している情報が含まれています。販売者のオークション スクリプトが検証を必要とする可能性のある情報です。

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

オークションが開始される前に、販売者は利用可能な広告スロットに最適なコンテキスト広告を見つけます。scoreAd() ロジックの一部では、コンテキスト広告の落札広告に勝てない広告はすべて拒否されます。

scoreAd()

scoreAd() は次の引数を取ります。

引数 ロール
adMetadata 購入者が提供する任意のメタデータ。
auctionConfig navigator.runAdAuction() に渡されるオークション構成オブジェクト。
bid 入札額の数値。
trustedScoringSignals オークション時に販売者の信頼できるサーバーから取得される値。広告に対する販売者の意見を表します。

よくある質問

オークションの落札者はどのように決定され、誰が選ぶのですか？

販売者は、各広告の望ましさスコアを決定するスコアリング ロジックを提供し、ブラウザは最高スコアを落札広告として選択します。

販売者は scoreAd() 関数にロジックを含め、ブラウザは外部のコードとの通信が制限されたワークレットで関数を実行します。ブラウザ自体は広告をスコアリングしません。ブラウザは、スコアリング ロジックを実行し、スコアが最も高い入札単価を選択する責任を単独で負います。

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

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

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