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 | 真|偽 | runAdAuction() から返された Promise を、true の場合は FencedFrameConfig に解決する(<fencedframe> で使用する場合)、false の場合は不透明な urn:uuid URL(<iframe> で使用する場合)に解決するよう指示するブール値です。デフォルトは false です。 |
非同期でシグナルを提供する
一部のシグナル(auctionSignals
、sellerSignals
、perBuyerSignals
、perBuyerTimeouts
フィールドで設定されるもの)の値は、具体的な値としてではなく、Promise として指定することもできます。これにより、スクリプトや信頼できるシグナルの読み込み、分離されたワークレット プロセスの起動など、オークションの一部で、これらの値の計算(またはネットワークの取得)をオーバーラップさせることができます。ワークレット スクリプトが参照するのは、解決された値のみです。そのような Promise が拒否された場合、すでに失敗しているか、他の方法で中止されていない限り、オークションは中止されます。
複数の販売者とのオークションを設定する
場合によっては、複数の販売者がオークションに参加し、別々のオークションの落札者が別の販売者のオークションに回されます。渡されるこれらの個別のオークションをコンポーネント オークションと呼びます。こうしたコンポーネント オークションを円滑に進めるために、componentAuctions
オブジェクトに販売者のコンポーネント オークションごとの追加のオークション設定を含めることができます。これらの各コンポーネント オークションの落札単価は「トップレベル」のオークションに渡され、オークションの最終決定が行われます。コンポーネント オークションの auctionConfig
に、独自の componentAuctions
がない場合があります。componentAuctions
が空でない場合、interestGroupBuyers
は空にする必要があります。つまり、特定の Protected Audience オークションで、販売者が 1 社でコンポーネント オークションが行われない場合、またはすべての入札がコンポーネント オークションから行われ、トップレベル オークションでコンポーネント オークションの落札者しか選択できない場合です。
オークションを実施する
販売者は、navigator.runAdAuction()
を呼び出して、ユーザーのブラウザに広告オークションの開始をリクエストします。
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
呼び出しは、広告に解決される Promise を返します。パブリッシャー ページ上のいかなるコードも、落札広告を検査したり、runAdAuction()
の結果からそのコンテンツを把握したりすることはできません。AuctionConfig
で resolveToConfig
フラグが true に設定されている場合は、フェンス付きフレーム内でのみレンダリングできる FencedFrameConfig
オブジェクトが返されます。このフラグが false に設定されている場合は、不透明な URN が返されます。これは iframe にレンダリングできます。runAdAuction が null 値(広告が選択されていないことを示す)を返すことがあります。この場合、販売者はコンテンツ ターゲット広告を表示する可能性があります。