広告スロットを購入するオークションに入札する

広告の購入者（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() は次の引数を取ります。

引数 ロール

interestGroup

 広告購入者から渡されたオブジェクト。インタレスト グループは dailyUpdateUrl で更新できます。

auctionSignals

 販売者から navigator.runAdAuction() に渡されるオークション設定引数のプロパティ。ページのコンテキスト（広告サイズ、パブリッシャー ID など）、オークションの種類（ファーストプライスまたはセカンドプライス）、その他のメタデータに関する情報を確認できます。

perBuyerSignals

 販売者から渡されたオークション設定引数のプロパティ。これにより、購入者のサーバーからページに関するコンテキスト シグナルを提供できます。販売者が SSP の場合、販売者のサーバーに対してリアルタイム ビッダーの呼び出しを行ってレスポンスを返す場合、またはパブリッシャーのページが購入者のサーバーに直接連絡している場合にこれが可能です。その場合、購入者は改ざんを防ぐために、generateBid() 内でこれらのシグナルの暗号署名をチェックできます。

trustedBiddingSignals

 キーがインタレスト グループの trustedBiddingSignalsKeys で、その値は trustedBiddingSignals リクエストで返されるオブジェクト。

browserSignals

 ブラウザによって作成されるオブジェクトです。これには、ページ コンテキストに関する情報（販売者が偽る可能性がある現在のページの hostname など）や、インタレスト グループ自体のデータ（そのグループが以前にオークションで落札した時点の記録など）が含まれ、オンデバイスのフリークエンシー キャップが可能になります。

directFromSellerSignals

 auctionSignals や sellerSignals は、runAdAuction が実行されるコンテキストに存在する任意の参加者から来る場合があります。これとは異なり、特定の販売者から送信されることが保証されているシグナルです。

ブラウザのシグナル

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
}
プロパティ 説明

topWindowHostname

 runAdAuction() 呼び出しが行われたホスト名。

seller

 入札先の販売者。コンポーネント オークションでは、この値はコンポーネントの販売者です。

topLevelSeller

 一部のオークションのトップレベルの販売者で、一部のオークションにのみ存在します。

requestedSize

 requestedSize プロパティは、オークションの推奨フレームサイズを示しています。販売者は、リクエストされたサイズをオークション設定に設定します。この値は generateBid() のビッダーに提供されます。オークションに参加するビッダーは、広告に異なるコンテンツ サイズを選択できます。選択したサイズは、要素のコンテナサイズ内に収まるように視覚的に調整されます。

joinCount

 joinCount フィールドは、インタレスト グループが継続的に保存されている（つまり、退会やメンバーシップの期限切れによりデバイス上のインタレスト グループのストレージにギャップがない）間に、過去 30 日間にこのデバイスがこのインタレスト グループに参加した回数です。

recency

 recency フィールドは、このデバイスがこのインタレスト グループに参加してから現在に至るまでの期間（分）です。

bidCount

 インタレスト グループが入札を行った回数。

prevWinsMs

 prevWinMs フィールドには、インタレスト グループが落札した広告と、それ以前に落札されてからの経過時間（ミリ秒単位）が含まれます。この広告オブジェクトには、renderURL フィールドとメタデータ フィールドのみが含まれています。

wasmHelper

 インタレスト グループの biddingWasmHelperURL に基づく WebAssembly.Module オブジェクト。

dataVersion

 購入者の Key-Value サービス レスポンスからの Data-Version 値。

adComponentsLimit

 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 複数の要素で構成される広告のコンポーネント（最大 20 個）のリスト（省略可）。navigator.joinAdInterestGroup() に渡されるインタレスト グループ引数の adComponents プロパティから取得されます。
allowComponentAuction この入札をコンポーネントのオークションで使用できるかどうかを示すブール値。デフォルトは false です。指定しない場合は、次のようになります。
bid オークションに参加する入札単価の数値。販売者は、さまざまな購入者の入札単価を比較できる立場にある必要があるため、入札単価は販売者が選択した単位（「USD」など）で行う必要があります。入札単価がゼロまたはマイナスの場合、このインタレスト グループは販売者のオークションに一切参加しません。この仕組みにより、購入者は、広告主のルールを指定して、広告の掲載場所と掲載しない場所を指定できます。
bidCurrency 入札の通貨。currency-checkingに使用されます。
render オークションで落札した場合にレンダリングされるクリエイティブを説明する辞書。これには次のものが含まれます。
<ph type="x-smartling-placeholder">
    </ph>
  • url: クリエイティブの URL。
  • width: クリエイティブの幅。このサイズはインタレスト グループの宣言と照合され、広告クリエイティブの URL に存在するすべての広告サイズマクロに置き換えられます。フェンスで囲まれたフレームに広告が読み込まれると、フェンスで囲まれたフレームの内側のフレーム（広告クリエイティブに表示されるサイズ）はこのサイズまで固定され、埋め込みツールによるフレームサイズの変更を確認できなくなります。
  • height: クリエイティブの高さ。width で詳しく説明しています。

modelingSignals

 0 ～ 4095 の整数（12 ビット）。ノイズを付加して reportWin() に渡されます。ノイズ化とバケット化のスキームをご覧ください。負の値、無限値、NaN 値などの無効な値は無視され、渡されません。下位 12 ビットのみが渡されます。


購入者は、generateBid() 関数内で利用可能なシグナル（userBiddingSignals のインタレスト グループの作成時に取得したファーストパーティの購入者データのデータを含む）を使用して、購入者の落札レポート関数に渡される値を導き出し、ML モデルのトレーニングを有効にできます。