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 つの段階](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=6&hl=ja)
- ユーザーが広告を表示するサイトにアクセスします。
- 販売者のコードが
navigator.runAdAuction()
を実行します。これにより、販売する広告スペースと入札できるユーザーを指定します。販売者は、各入札をスコアリングするスクリプトscoreAd()
も含める必要があります。 - 招待された購入者のコードが実行され、入札単価、関連する広告クリエイティブの URL、その他のデータが生成されます。入札スクリプトでは、購入者の Key-Value サービスからリアルタイム データ(広告キャンペーンの予算の残額など)をクエリできます。
- 販売者のコードによって各入札が評価され、落札者が決まります。このロジックでは入札単価の値を使用します。その他のデータは入札の望ましい結果を返します。落札できなかった広告は承認されません。販売者は、独自の Key-Value サービスを使用してリアルタイム データを取得できます。
- 落札された広告は不透明な値として返され、フェンス付きフレームに表示されます。販売者とパブリッシャーのどちらも、この値を表示できません。
- オークションは販売者と落札購入者にレポートされます。
オークションはいつ行われますか?
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 を返します。これをブラウザでデコードできるのは、レンダリング用のフェンス付きフレームに渡されたときのみです。パブリッシャーのページでは落札された広告を検査できません。
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 のデベロッパー ガイド。
- Protected Audience のインタレスト グループと入札の生成に関する広告購入者向けガイド。
- Protected Audience の広告オークションに関する広告販売者向けガイド。
- オークション結果のレポートに関するガイド
- Protected Audience の広告オークションの遅延に関するベスト プラクティス
- Protected Audience のトラブルシューティング
Protected Audience API の解説では、機能のサポートと制約に関する詳細も説明しています。