売り手向けガイド: 広告オークションを実行する

この記事では、実験的な Protected Audience API の現在のイテレーションで使用されている、広告オークションの技術リファレンスを紹介します。

Protected Audience API のライフサイクル全体については開発者ガイドを参照し、売り手によるオンデバイス オークションの実行方法の詳細なディスカッションについては Protected Audience API の Explainer をご覧ください。

開発者でない方は、Protected Audience API の概要をご覧ください。

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

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

1. ユーザーが広告を表示するサイトにアクセスします。
2. 売り手のコードは navigator.runAdAuction() を実行します。これにより、どの広告スペースが販売され、誰が入札できるかが指定されます。売り手は、 scoreAd() という各入札をスコアリングするスクリプトも含める必要があります。

3. 招待された買い手のコードが実行され、入札、関連する広告クリエイティブの URL、およびその他のデータが生成されます。入札スクリプトは、買い手の [Key/Value サービス](/docs/privacy-sandbox/protected-audience#key-value-service-detail) から、残りの広告キャンペーン予算などのリアルタイム データをクエリできます。 4. 売り手のコードが各入札をスコアリングし、落札者を選択します。このロジックでは、入札値と入札の望ましさを返す他のデータを使用します。コンテキストの落札者に勝てない広告は拒否されます。売り手は、リアルタイム データに独自の[Key/Value サービス](/docs/privacy-sandbox/protected-audience#key-value-service-detail) を使用できます。 5. 落札した広告は opaque 値として返され、Fenced Frame
に表示されます。売り手とサイト運営者のいずれもこの値を閲覧できなくなります。 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 を返します。これは、レンダリングのために Fenced Frame に渡された場合にのみ、ブラウザによってデコードできます。したがってサイト運営者のページは、落札した広告を検査できません。

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() は次の引数を取ります。

# よくある質問

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

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

売り手は、scoreAd() 関数にロジックを組み込み、ブラウザは、外部のコードとの通信が制限されているワークレット内で関数を実行します。ブラウザ自体は広告をスコアリングしません。スコアリング ロジックを実行して最高スコアの入札を選択するタスクは、ブラウザに排他的に当てられています。

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

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

• Protected Audience API の開発者ガイド。
• Protected Audience インタレストグループと入札生成に関する広告バイヤーガイド。
• Protected Audience 広告オークションに関する広告セラーガイド。
• オークション結果のレポートに関するガイド
• Protected Audience 広告オークションのレイテンシに関するベストプラクティス
• Protected Audience のトラブルシューティング

Protected Audience API の Explainer には、機能のサポートと制約に関する詳細が提供されています。