広告購入者(DSP と広告主)は、パブリッシャー サイトでの Protected Audience 広告オークションに参加して、広告主のサイトで定義したインタレスト グループを広告のターゲットにすることができます。Protected Audience オークションに参加すると、プライバシーを保護しながら、他のサイト上で対象の顧客にリーチできます。
Protected Audience のオークションでは、お客様が入札を生成するロジックを提供すると、ブラウザがそのロジックを使って入札単価を計算します。この点が、ロジックではなく入札を直接送信する他のオークション アーキテクチャとは対照的です。
generateBid()
JavaScript 関数に入札生成ロジックを指定すると、このファイルがサーバーでホストされます。ユーザーをインタレスト グループに追加すると、このファイルの場所が biddingLogicUrl
としてインタレスト グループの設定に渡されます。
オークション中、ブラウザは biddingLogicUrl
フィールドに指定された入札ロジックを取得し、外部コンテキストとの通信が制限された安全な隔離環境で、インタレスト グループごとに generateBid()
関数を実行します。generateBid()
が実行されると、ブラウザはシグナルを引数として関数に渡します。これらのシグナルには、パブリッシャーの自社データ、販売者のデータ、リアルタイム データなど、さまざまなソースからのさまざまな情報が含まれています。これらのシグナルを使って入札単価を計算すると、値は generateBid()
呼び出しから返されます。入札が送信されると、ブラウザは各入札に対して販売者のスコアリング ロジックを実行し、販売者の好意度スコアを計算します。
generateBid()
以下では、generateBid()
関数の引数と、この関数から返される入札単価の構造について説明します。
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals, directFromSellerSignals) {
return {
ad: adObject,
adCost: optionalAdCost,
bid: bidValue,
bidCurrency: 'USD',
render: {
url: renderURL,
width: renderWidth,
height: renderHeight
},
adComponents: [
{url: adComponent1, width: componentWidth1, height: componentHeight1},
{url: adComponent2, width: componentWidth2, height: componentHeight2},
// ...
],
allowComponentAuction: false,
modelingSignals: 123 // 0-4095 integer (12-bits)
};
}
引数
generateBid()
は次の引数を取ります。
引数 | ロール |
---|---|
|
広告購入者から渡されたオブジェクト。このインタレスト グループは「dailyUpdateUrl 」で更新される可能性があります。 |
|
販売者が navigator.runAdAuction() に渡すオークション設定引数のプロパティ。これにより、ページのコンテキスト(広告サイズやパブリッシャー ID など)、オークションのタイプ(ファーストプライスまたはセカンドプライス)、その他のメタデータに関する情報が提供されます。 |
|
販売者が渡したオークション設定引数のプロパティ。販売者のページが購入者のサーバーに対してリアルタイム ビッダー呼び出しを行い、レスポンスをパイプで返す SSP の場合、またはパブリッシャーのページが購入者のサーバーに直接連絡している場合は、購入者のサーバーからページに関するコンテキスト シグナルを提供できます。その場合は、改ざんを防ぐために generateBid() 内でこれらのシグナルの暗号署名をチェックすることをおすすめします。 |
|
キーはインタレスト グループの trustedBiddingSignalsKeys で、その値は trustedBiddingSignals リクエストで返されます。 |
|
ブラウザによって作成されるオブジェクト。ページのコンテキストに関する情報(現在のページの hostname など、販売者は偽造できるもの)とインタレスト グループ自体のデータ(そのグループが過去にオークションで落札した際の記録など、デバイス上のフリークエンシー キャップを有効にするため)を含むことがあります。 |
|
特定の販売者からであることが保証されているシグナル。runAdAuction が実行されたコンテキストに存在するすべての参加者から得られる auctionSignals や sellerSignals とは異なります。 |
ブラウザのシグナル
browserSignals
オブジェクトには次のプロパティがあります。
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
topLevelSeller: 'https://www.top-level-ssp.com',
requestedSize: {width: 100, height: 200}, /* if specified in auction config */
joinCount: 3,
recency: 3600000,
bidCount: 17,
prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
wasmHelper: ...
dataVersion: 1,
adComponentsLimit: 40
}
プロパティ | 説明 |
---|---|
|
runAdAuction() 呼び出しが行われたホスト名。 |
|
入札先の販売者。コンポーネント オークションでは、この値はコンポーネント販売者です。 |
|
コンポーネント オークションの最上位の販売者で、コンポーネント オークションにのみ参加します。 |
|
requestedSize プロパティは、オークションでの推奨フレームサイズです。販売者がリクエストされたサイズをオークション設定で設定すると、その値は generateBid() のビッダーで利用可能になります。オークションに参加するビッダーは、広告に対して別のコンテンツ サイズを選択することがあります。その結果、要素のコンテナサイズに収まるように視覚的にスケーリングされます。 |
|
joinCount フィールドは、インタレスト グループが継続的に保存されている中で、過去 30 日間にこのデバイスがこのインタレスト グループに参加した回数です(つまり、離脱やメンバーシップの期限切れによって、デバイス上のインタレスト グループのストレージにギャップはありません)。 |
|
[recency ] フィールドは、このデバイスがこのインタレスト グループに参加してから現在までの時間です(分単位)。 |
|
インタレスト グループが入札を送信した回数。 |
|
prevWinMs フィールドには、インタレスト グループで落札された広告と、それ以前の広告が落札してからの時間(ミリ秒単位)が含まれます。ここでの広告オブジェクトに含まれるのは renderURL フィールドと metadata フィールドのみです。 |
|
インタレスト グループの biddingWasmHelperURL に基づく WebAssembly.Module オブジェクト。 |
|
購入者の Key-Value サービス レスポンスから取得した Data-Version 値です。 |
|
generateBid() が返す広告コンポーネントの最大数 |
入札単価を計算する
入札単価を計算するには、generateBid()
のコードで関数のパラメータのプロパティを使用します。
次に例を示します。
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
// ...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
// ...
}
}
入札単価を返す
generateBid()
は、次のプロパティを持つオブジェクトを返します。
プロパティ | ロール |
---|---|
ad |
広告に関する任意のメタデータ。たとえば、この入札や広告クリエイティブについて販売者が知りたい情報など。販売者はオークションと判断ロジックでこの情報を使用します。 |
adCost |
レポート対象の広告主のクリックまたはコンバージョンの費用を generateBid から reportWin に渡すために使用される数値。この数値の精度は 8 ビットの仮数と 8 ビットの指数に制限され、丸めは確率論的に行われます。 |
adComponents |
navigator.joinAdInterestGroup() に渡されるインタレスト グループ引数の adComponents プロパティから取得された、複数の要素で構成される広告のコンポーネントを最大 20 個含むオプションのリスト。 |
allowComponentAuction |
この入札単価をコンポーネント オークションで使用できるかどうかを示すブール値。指定しない場合のデフォルトは「false」です。 |
bid |
オークションに参加する入札単価の数値。販売者は複数の購入者の入札を比較できる立場にある必要があるため、入札単価は販売者が選択した単位(「USD/1000」など)で指定する必要があります。入札単価がゼロまたは負の場合、このインタレスト グループは販売者のオークションにまったく参加しません。このメカニズムにより、購入者は広告の掲載先に関する広告主のルールを実装できます。 |
bidCurrency |
入札単価の通貨。通貨のチェックに使用されます。 |
render |
オークションで落札した場合にレンダリングされるクリエイティブを記述するディクショナリ。これには以下が含まれます。
|
|
ノイズとバケット化のスキームで説明されているように、ノイズ付きで reportWin() に渡される 0 ~ 4,095 の整数(12 ビット)。無効な値(負の値、無限の値、NaN の値など)は無視され、渡されません。下位 12 ビットのみが渡されます。購入者は generateBid() 関数内で利用可能なシグナル(userBiddingSignals のインタレスト グループ作成時に取得した自社購入者データからのデータなど)を使用して、購入者の落札レポート機能に渡される値を取得し、ML モデルのトレーニングに使用できます。 |