購入者として B&A と統合する

入札とオークション(B&A)サービスは、広告の購入者と販売者向けのサービス群です。高信頼実行環境(TEE)で実行され、Protected Audience(PA)オークションを促進します。このデベロッパー ガイドでは、Chrome の B&A PA オークションに購入者が統合する方法について説明します。

概要

B&A サービスを使用して Protected Audience オークションに参加するには、購入者はインタレスト グループ(IG)を更新してペイロードを最適化し、オークションのレイテンシを短縮します。

購入者は、次のペイロードの最適化タスクを行う必要があります。

B&A のインタレスト グループ

ペイロードの最適化が適用された B&A PA オークションのインタレスト グループの設定例を次に示します。

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

B&A とオンデバイスのインタレスト グループの設定の違いは次のとおりです。

フィールド B&A IG オンデバイス IG B&A オークション ペイロードに含まれる
auctionServerRequestFlags 使用済み 不使用 いいえ
userBiddingSignals 非推奨 使用済み いいえ(omit-user-bidding-signals フラグが設定されている場合)
adsadComponentsadRenderId 使用済み 不使用 omit-ads フラグが設定されている場合、adsadRenderId はペイロードの browserSignals.prevWins でのみ使用できます。adComponents で定義された adRenderId はペイロードに含まれません。

omit-ads フラグが設定されていない場合、browserSignals.prevWinsinterestGroup.adRenderIdsinterestGroup.adComponentRenderIds で使用できます。

adsadComponentsrenderURL 使用済み 使用済み いいえ
adsadComponentsmetadata 不使用 使用済み いいえ
ads のレポート ID 使用済み 使用済み いいえ
  • auctionServerRequestFlags フィールドでは、B&A オークション ペイロードの一部のデータの省略をブラウザに指示するフラグを設定できます。
  • userBiddingSignals 値はインタレスト グループで定義できますが、omit-user-bidding-signals フラグを使用して省略することをおすすめします。省略されたシグナルは、K/V サービスを使用して指定できます。
  • adRenderId フィールドは、関連する renderURL とともに設定されますが、B&A オークション ペイロードの一部となるのは adRenderId のみです。オークション時間中に generateBid() から返されるレンダリング URL は、IG で定義されたレンダリング URL と一致する必要があります。
  • レポート ID は B&A IG で定義されますが、B&A オークション ペイロードには含まれません。オークション時間中に generateBid() から返されたレポート ID は、IG で定義されたレンダリング URL と一致している必要があります。
  • ad.metadata とレポート ID は B&A オークション ペイロードには含まれません。代わりに、信頼できる Key-Value サービスの使用を通じてこれらのデータが利用可能になります。

adsrenderURL とレポート ID は引き続きインタレスト グループの設定で定義されますが、オークション リクエスト ペイロードには含まれません。これは、ブラウザが、Bidding Service の generateBid() 関数から返されたレンダリング URL とレポート ID が、インタレスト グループで定義された値と一致することを確認するためです。

joinAdInterestGroup() 件のタスク

joinAdInterestGroup() 呼び出しでは、次のタスクを実行する必要があります。

サーバー リクエスト フラグを設定する

joinAdInterestGroup() 構成の auctionServerRequestFlags フィールドには、次のフラグを指定できます。

フラグ 説明
omit-user-bidding-signals omit-user-bidding-signals フラグを使用すると、オークション ペイロードの userBiddingSignals オブジェクトが省略されます。

このフラグが設定されていない場合、インタレスト グループで定義された userBiddingSignals 値が Bidding Service の generateBid() 内で使用可能になります。

omit-ads omit-ads フラグは、オークション ペイロードの ads オブジェクトと adComponents オブジェクトを省略するようブラウザに指示します。

adRenderIdbrowserSignalsprevWins プロパティで使用できます。

このフラグが設定されていない場合、generateBid()interestGroup 引数の adRenderIds フィールドと adComponentRenderIds フィールドには、対応する広告レンダリング ID が含まれます。

購入者は omit-ads フラグを選択することを強くおすすめします。今後、ペイロードの最適化を進めるため、クライアントからレンダリング ID と広告コンポーネントのレンダリング ID を渡すことが非推奨になる可能性があります。

省略されたデータは、trustedBiddingSignals で関連情報を利用できるようにすることで処理されます。これらのフラグは個別に使用できます。併用する必要はありません。

使用例:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

広告レンダリング ID を設定する

B&A オークション ペイロードのサイズを小さくするため、インタレスト グループの ads オブジェクトと adComponents オブジェクトは省略されます。これにより、これらのオブジェクトは Bidding Service で実行される generateBid() 関数内で使用できなくなります。

不足している広告情報を処理するため、購入者はインタレスト グループの設定で各広告に関連付けられた ID(adRenderIdadComponentRenderId)を保持します。識別子は、長さが 12 バイト以下の DOMString にする必要があります。ID が Base64 でエンコードされている場合、その長さは 12 バイト以下にする必要があります。

広告レンダリング ID を含むインタレスト グループの例:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

広告に関連付けられている adRenderId は、generateBid()prevWins.browserSignals で利用できるようになります。

renderURL はリクエスト ペイロードに含まれませんが、generateBid() から返されたレンダリング URL は、インタレスト グループの設定で定義されたレンダリング URL と一致している必要があります。広告テクノロジーは、trustedBiddingSignals で広告メタデータなどの情報を返すことができます。これにより、generateBid() の実行中に、入札の広告レンダリング URL と広告コンポーネントのレンダリング URL を生成できます。

インタレスト グループの優先度を設定する

Chrome では、購入者がインタレスト グループの優先度を設定できます。販売者が設定した購入者ごとのペイロード サイズの上限に達すると、販売者に対して B&A オークション ペイロードが生成されるときに、インタレスト グループの優先度値を使用して、単一の購入者の優先度の低いインタレスト グループが除外されます。異なる購入者間でインタレスト グループを選択する場合、ブラウザはシリアル化されたペイロードのサイズに基づいて決定します。デフォルトでは、各購入者に同じサイズが割り当てられます。実際の優先順位付けは、リクエスト ペイロードの生成時ではなく、B&A サーバーで行われます。

優先度は、オークション時に購入者の優先ベクトル(priorityVector)と販売者の優先シグナル(prioritySignals)を使用して計算されます。購入者は販売者の優先シグナルをオーバーライドできます。

プロパティ 説明
優先ベクトル 購入者は、K/V サービスの priorityVector キーの値としてベクトルを指定します。
優先シグナル 販売者は、オークション構成の priority_signals を設定してシグナルを提供します。
優先シグナルのオーバーライド 購入者は、オークション構成の PerBuyerConfigpriority_signals_overrides フィールドでオーバーライドを指定します。

オークション中に、ブラウザは優先度について、priorityVectorprioritySignals の一致するキーのスパース ドット積を計算します。次の図では、優先度は (4 * 2) + (3 * -1) で計算され、8 + -3 に減らされます。そのため、オークション時のこのインタレスト グループの優先度は 5 です。

優先度ベクトルと優先度シグナル オブジェクトの各キーを相互に掛け合わせ、その結果を合計して優先度を計算します。
図 1: 購入者のベクトルと販売者のシグナルを使用した優先度の計算

B&A の優先順位付けに使用できる追加のシグナルもあります。

シグナル 説明
deviceSignals.one 値は常に 1 で、ドット積に定数を追加する場合に便利です。
deviceSignals.ageInMinutes この値は、興味 / 関心グループの存続期間(直近の興味 / 関心グループへの参加からの経過時間)を分単位で表す整数(0 ~ 43,200)です。
deviceSignals.ageInMinutesMax60 この値は ageInMinutes シグナルと同じですが、最大値は 60 です。グループが 1 時間以上経過している場合は、60 が返されます。
deviceSignals.ageInHoursMax24 この値は、インタレスト グループの存続期間(最大 24 時間)を時間単位で表します。グループが 1 日以上経過している場合は、24 が返されます。
deviceSignals.ageInDaysMax30 この値は、インタレスト グループの存続日数(最大 30 日)を表します。グループの作成から 30 日以上経過している場合は、30 が返されます。

詳しくは、GitHub の説明をご覧ください。

信頼できる入札シグナルを設定する

一部のデータは B&A オークション ペイロードから除外されるため、Key-Value サービスを使用して、除外されたデータを信頼できる入札シグナルとして generateBid() 関数に提供できます。

省略された次のデータを K/V サービスから提供できます。

  • userBiddingSignals(購入者が使用した場合)
  • 各広告に関連付けられた metadata
  • 各広告に関連付けられた adRenderId
  • レポート ID
興味 / 関心グループから除外されたデータは、購入者の収集サーバーに送信できます。収集サーバーがデータを Key-Value サービスにプッシュし、後でブラウザが Key-Value サービスからデータを読み込みます。
図 2: 信頼できるシグナルの設定例

信頼できる入札シグナルのキーに一意の ID を含め、関連データをサーバーに送信して Key-Value サービスに読み込めるようにする方法があります。ただし、実際の実装は広告テクノロジーに委ねられており、API は指示的なものではありません。

次の例は、実装できるアプローチの一つを示しています。

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

この例では、IG に一意の識別子が定義され、信頼できるシグナル鍵の一部になります。IG のキーとそれに関連付けられた値はサーバーに送信され、Key-Value サービスに読み込まれます。オークションの後の時点で、ブラウザは信頼できるシグナルを取得し、購入者の generateBid() 関数で使用できるようにします。

必要に応じて、K/V からインタレスト グループの更新シグナルを返す

信頼できるシグナルの updateIfOlderThanMs キーは、通常の 1 日間隔よりも早くインタレスト グループを更新するために使用されます。updateIfOlderThanMs キーに対して返されたミリ秒値を超える時間内にインタレスト グループが結合または更新されていない場合、インタレスト グループは updateURL メカニズムで更新されます。Chrome では、興味 / 関心グループは 10 分に 1 回以上更新されません。

B&A オークションで、ブラウザに保存されているインタレスト グループで定義されている広告のいずれにも一致しない落札広告が返された場合、ブラウザはオークションに失敗します。updateIfOlderThanMs メカニズムは、ブラウザと B&A オークションがインタレスト グループ内の広告セットについて合意できるようにするのに役立ちます。

詳しくは、説明をご覧ください。

generateBid() 件のタスク

generateBid() 呼び出しでは、次のタスクを実行する必要があります。

ブラウザ シグナルを読み取る

B&A generateBid() 呼び出しに渡される browserSignals オブジェクトは次のようになります。

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

browserSignals では、次の変更済みまたは新規のプロパティを使用できます。

プロパティ 説明
prevWins prevWins は、時間と広告のタプルの配列です。この時間は、過去 30 日間に関連付けられた広告が最後に落札してから経過した秒数を表します。

ad オブジェクトではなく adRenderId を提供するように変更されました。

wasmHelper biddingWasmHelperURL から提供されたコードのコンパイル済みオブジェクト。
dataVersion 信頼できるサーバーは、generateBid() で使用できる数値の Data-Version レスポンス ヘッダーを含めることができます。

詳しくは、GitHub の説明をご覧ください。

generateBid() からレンダリング URL を返す

B&A オークション ペイロードでは ads オブジェクトが省略されるため、generateBid() から返されたレンダリング URL を再作成する必要があります。レンダリング URL の再作成方法は実装によって決まります。返される URL は、インタレスト グループで定義されたレンダリング URL と一致する必要があります。

ベース URL を維持し、interestGrouptrustedBiddingSignals の情報でテンプレートを入力するという方法があります。

この例では、色と商品に基づいて 4 つの広告を定義しています。

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

次に、ユーザーの好みの色と商品情報を送信して、Key/Value サービスに読み込みます。

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

後でオークションが実行されると、信頼できる入札シグナルが generateBid() で利用可能になり、その情報を使用して URL を再構築できます。

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

generateBid() からレポート ID を返す

レポート ID は B&A オークション ペイロードに含まれないため、信頼できる入札シグナルを介して generateBid() が ID を利用できるようになります。使用するレポート ID が決定されると、選択したレポート ID が generateBid() から返されます。返された ID は、インタレスト グループで定義された ID と一致している必要があります。

この例では、広告 1 が選択され、それに関連付けられたレンダリング ID が generateBid() から返されます。

generateBid(..., trustedBiddingSignals, ) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

返されたレポート ID は、reportWin()buyerReportingSignals で使用できます。

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

generateBid() から buyerReportingId が返されない場合、buyerReportingId ではなく buyerReportingSignalsinterestGroupName 値を使用できます。

詳しくは、レポート ID ガイドをご覧ください。

次のステップ

次のリソースをご利用いただけます。

その他の情報

ご不明な点がある場合