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

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

概要

B&A サービスで Protected Audience オークションに参加するには、バイヤーがインタレスト グループ（IG）を更新して、オークションのレイテンシを改善するためにペイロードを最適化します。

購入者は次のペイロード最適化タスクを必要とします。

• joinAdInterestGroup() タスク
  • サーバー リクエスト フラグを設定する
  • 広告レンダリング ID を設定する
  • インタレスト グループの優先度を設定する
  • 信頼できる入札シグナルを設定する
• generateBid() タスク
  • ブラウザのシグナルを読み取る
  • Return render URL
  • Return reporting ID（返品レポート ID）

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 とオンデバイスのインタレスト グループ設定の違いは次のとおりです。

• 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 オークション ペイロードに含まれていません。代わりに、これらのデータは Trusted Key/Value Service の使用を通じて利用可能になります。

renderURL と ads のレポート ID はインタレスト グループ構成で定義されていますが、オークション リクエスト ペイロードには含まれません。これは、ブラウザが、入札サービスの generateBid() 関数から返されたレンダリング URL とレポート ID が、インタレスト グループで定義された値と一致することを確認するためです。

joinAdInterestGroup() 件のタスク

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

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

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

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

使用例:

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

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

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

広告情報の欠落に対処するため、購入者はインタレスト グループ設定の各広告に関連付けられた識別子（adRenderId と adComponentRenderId）を保持します。識別子は 12 バイト以下の DOMString である必要があります。識別子が 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）を使用してオークション時に計算されます。購入者は販売者の優先度シグナルをオーバーライドできます。

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

B&A で優先順位付けに使用できる追加シグナルは次のとおりです。

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

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

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

次の省略されたデータは、K/V サービスによって提供できます。

• 購入者が使用している場合は userBiddingSignals
• 各広告に関連付けられた metadata
• 各広告に関連付けられた adRenderId
• レポート ID

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

次の例では、実装可能なアプローチの 1 つについて説明します。

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 キーは、通常の日次間隔よりも早くインタレスト グループを更新するために使用されます。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 では、次の変更または新しいプロパティを使用できます。

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

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

1 つの方法として、ベース URL を維持し、interestGroup と trustedBiddingSignals の情報でテンプレートを入力することが考えられます。

この例では、色と商品に基づいて 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 は、buyerReportingSignals を介して reportWin() で使用できるようになります。

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

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

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

次のステップ

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

その他の情報

• 詳しくは、Chrome での B&A オークションの構成をご覧ください。
• エンドツーエンドのローカル テストの Codelab に沿って、B&A で Protected Audience をテストします。

ご不明な点がある場合

• 入札とオークション サービスについてご不明な点がある場合は、B&A サービス リポジトリで issue を作成してください。