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

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

Protected Audience API の広告オークションに関する Seller 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 の広告オークションの各ステージの概要を示しています。

ユーザーが広告を表示するサイトにアクセスします。
販売者のコードが navigator.runAdAuction() を実行します。これにより、販売する広告スペースと入札できるユーザーを指定します。販売者は、各入札をスコアリングするスクリプト scoreAd() も含める必要があります。
注: 販売者はオークションの開始前に、利用可能な広告スロットに最適なコンテキスト広告を見つけます。
招待された購入者のコードが実行され、入札単価、関連する広告クリエイティブの URL、その他のデータが生成されます。入札スクリプトでは、購入者の Key-Value サービスからリアルタイムデータ（広告キャンペーンの予算の残額など）をクエリできます。
販売者のコードによって各入札が評価され、落札者が決まります。このロジックでは入札単価の値を使用します。その他のデータは入札の望ましい結果を返します。落札できなかった広告は承認されません。販売者は、独自の Key-Value サービスを使用してリアルタイムデータを取得できます。
落札された広告は不透明な値として返され、フェンス付きフレームに表示されます。販売者とパブリッシャーのどちらも、この値を表示できません。
オークションは販売者と落札購入者にレポートされます。
注: 販売者の reportResult() と購入者の reportWin() には、sendReportTo() の呼び出しを含めることができます。これは、プライベートアグリゲーションで集計レポートが利用可能になるまで、一時的に利用できます。

オークションはいつ行われますか？

Protected Audience API は単独で運用することも、プログラマティックオークションで運用することもできます。複数販売者によるプログラマティックオークションでは、次の処理が行われます。

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

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

Protected Audience API の広告オークションの運営者

広告スペースを販売するオークションには、複数の関係者が参加します。

次に例を示します。

コンテンツパブリッシャー: 自らのウェブサイトで広告コンテンツをホストするためのサービス。
サプライサイドプラットフォーム（SSP）: パブリッシャーと連携してその他のサービスを提供。
第三者スクリプト: 広告オークションに参加できるように、パブリッシャーを代理するスクリプト。

Protected Audience API を使用する営業担当者は、

パブリッシャーのルールを適用して、どの購入者とどの入札が対象となるかを適用する。
オークションロジックの実行: 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 を返します。これをブラウザでデコードできるのは、レンダリング用のフェンス付きフレームに渡されたときのみです。パブリッシャーのページでは落札された広告を検査できません。

注: joinAdInterestGroup() のスクリプトの生成元は、インタレストグループのオーナーのオリジンと一致している必要があるため、インタレストグループのオーナーのオリジンが現在のドキュメントの生成元（独自のインタレストグループを持つウェブサイトなど）と一致する場合を除き、joinAdInterestGroup() を iframe から（DSP などから）呼び出す必要があります。 runAdAuction には同じ要件がないため、<script> タグを使用したほうが、クロスオリジンの iframe よりもはるかにパフォーマンスが高い可能性があります。

decisionLogicUrl スクリプトは、個々の広告とそれに関連付けられている入札単価およびメタデータを 1 つずつ検討し、数値の望ましいスコアを割り当てます。

`auctionConfig` 件の宿泊施設

注: additionalBids は Protected Audience API の現在の実装ではサポートされていません。詳しくは、Protected Audience API 説明ページのオークション参加者のセクションをご覧ください。

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 のデベロッパーガイド。
Protected Audience のインタレストグループと入札の生成に関する広告購入者向けガイド。
Protected Audience の広告オークションに関する広告販売者向けガイド。
オークション結果のレポートに関するガイド
Protected Audience の広告オークションの遅延に関するベストプラクティス
Protected Audience のトラブルシューティング

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