買い手向けガイド: インタレスト グループに参加して入札を生成する

この記事では、実験的な Protected Audience API の現在のイテレーションで使用されている、インタレスト グループの技術リファレンスを紹介します。

Protected Audience API のライフサイクル全体については開発者ガイドを読み、ブラウザによるインタレスト グループの記録方法に関する詳細な提案については Protected Audience API の Explainer をご覧ください。

開発者でない方は、Protected Audience API の概要をご覧ください。

# Protected Audience API インタレスト グループ

Protected Audience API インタレスト グループは、共通の関心を持つユーザーをリマーケティング リストに対応してグループ化したものです。すべての Protected Audience API インタレスト グループにはオーナーが存在します。

インタレスト グループのオーナーは、Protected Audience API 広告オークションの買い手として機能します。インタレスト グループのメンバーシップはブラウザによってユーザーのデバイスに保存されるものであり、ブラウザのベンダーや他の誰とも共有されることはありません。

# Protected Audience API 広告オークションに入札する

Protected Audience API インタレスト グループのオーナーは、Protected Audience API 広告オークションへの入札に招待されます。

# API 関数

# joinAdInterestGroup()

広告主のデマンドサイド プラットフォーム（DSP）または広告主自体は、navigator.joinAdInterestGroup() を呼び出して、ブラウザに対し、ブラウザのメンバーシップ リストにインタレスト グループを追加するよう要求します。

joinAdInterestGroup() の呼び出し元コンテキストのオリジンは、インタレスト グループのオーナーのオリジンと一致する必要があるため、joinAdInterestGroup() は、インタレスト グループのオーナーのオリジンと現在のドキュメントのオリジンが一致しない限り（たとえば、独自のインタレスト グループを持つウェブサイト）、iframe から呼び出す必要があります。

joinAdInterestGroup() には以下からの許可が必要です。

• アクセスされているサイト
• インタレスト グループのオーナー

つまり、dsp.example.com が許可を付与しない限り、malicious.example は dsp.example.com が所有するインタレスト グループに対して joinAdInterestGroup() を呼び出せないということです。

# アクセスされているサイトからの許可

許可は、同じオリジンまたはクロスオリジンから付与できます。

デフォルトでは、アクセスされているサイトと同じオリジン（現在のページのトップレベル フレームと同じオリジン）からの joinAdInterestGroup() 呼び出しに対して許可が付与されます。サイトは、join-ad-interest-group 権限ポリシーヘッダーを使用して、joinAdInterestGroup() 呼び出しを無効にすることができます。

joinAdInterestGroup() クロスオリジン（現在のページとは異なるオリジン）の呼び出しは、アクセスされているサイトがクロスオリジン iframe からの joinAdInterestGroup() の呼び出しを許可する権限ポリシーを設定している場合にのみ成功します。

# インタレスト グループのオーナーからの許可

インタレスト グループのオーナーの許可は、インタレスト グループのオーナーと同じオリジンを持つ iframe から joinAdInterestGroup() を呼び出すことによって暗黙的に付与されます。たとえば、dsp.example.com iframe は、 dsp.example.com が所有するインタレスト グループに対して joinAdInterestGroup() を呼び出すことができます。

基本的に、joinAdInterestGroup() はオーナーのドメインのページまたは iframe で実行されるか、.well-known URL のリストを使用して提供される他のドメインに委譲されます。

# 使用例

以下は、インタレスト グループを定義し、ブラウザにグループへの参加を要求する方法を例で示しています。

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

関数に渡される interestGroup オブジェクトのサイズは 50 kiB を超えてはいけません。超えてしまうと、呼び出しは失敗します。2 番目のパラメーターは、インタレスト グループの期間を指定します。上限は 30 日です。連続して呼び出すと、以前に保存された値が上書きされます。

# 必須のプロパティ

インタレスト グループに必要なプロパティは、owner と name のみです。

# オプションのプロパティ

残りのプロパティはオプションです。

biddingLogicUrl^{1、2 _}

例: https://dsp.example/bid/custom-bikes/bid.js

役割: ワークレットで実行される入札 JavaScript の URL。

biddingWasmHelperUrl^{1、2 _}

例: https://dsp.example/bid/custom-bikes/bid.wasm

役割: biddingLogicUrl から駆動される WebAssembly コードの URL。

dailyUpdateUrl

2

例: https://dsp.example/bid/custom-bikes/update

役割: インタレスト グループの属性を更新する JSON を返す URL。（インタレスト グループを更新するをご覧ください。）

trustedBiddingSignalsUrl

2

例: https://dsp.example/trusted/bidding-signals

役割: 入札者の信頼できるサーバーへの Key-Value リクエストのベース URL。

trustedBiddingSignalsKeys

例: ['key1', 'key2' ...]

役割: Key-Value の信頼できるサーバーへのリクエストのキー。

userBiddingSignals

例: {...}

役割: オーナーが入札中に使用できる追加のメタデータ。

ads

1

例: [bikeAd1, bikeAd2, bikeAd3]

役割: このインタレスト グループ向けにレンダリングされる可能性のある広告。

adComponents

例: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

役割: 複数の部分で構成される広告のコンポーネント。

¹ The `biddingLogicUrl` and `ads` properties are optional, but required to participate in an auction. There may be use cases for creating an interest group without these properties: for example, an interest group owner might want to add a browser to an interest group for a campaign that isn't running yet, or for some other future use, or they may temporarily have run out of advertising budget.

² In the current implementation of the Protected Audience API, `biddingLogicUrl`, `biddingWasmHelperUrl`, `dailyUpdateUrl` and `trustedBiddingSignalsUrl` must have the same origin as owner. That may not be a long-term constraint, and the `ads` and `adComponents` URLs have no such constraint.

# 属性の更新

dailyUpdateUrl は、joinAdInterestGroup() に渡されるインタレスト グループ オブジェクトに対応してインタレスト グループ プロパティを定義する JSON を返すウェブサーバーを指定します。

これにより、グループのオーナーは、インタレスト グループの属性を定期的に更新できます。現在の実装では、次の属性を変更できます。

• biddingLogicUrl
• biddingWasmHelperUrl
• trustedBiddingSignalsUrl
• trustedBiddingSignalsKeys
• ads
• priority

JSON で指定されていないフィールドは上書きされず、JSON で指定されたフィールドのみが更新されますが、navigator.joinAdInterestGroup() を呼び出すと、既存のインタレスト グループが上書きされます。

更新はベストエフォートであり、次の条件では失敗する可能性があります。

• ネットワーク リクエストのタイムアウト（現在 30 秒）。
• その他のネットワーク障害。
• JSON 解析の失敗。

更新は 1 日あたり最大 1 回に制限されています。

更新に連続して長い時間が費やされた場合には、更新がキャンセルされることもありますが、これによりキャンセルされた（残りの）更新にレート制限が課されることはありません。ネットワーク エラーが原因で失敗した更新は 1 時間後に再試行され、インターネットからの切断が原因で失敗した更新は再接続後にすぐに再試行されます。

# 手動更新

現在のフレームのオリジンが所有するインタレスト グループの更新は、navigator.updateAdInterestGroups() を介して手動でトリガーできます。

レート制限により、更新が頻繁に行われることが防止されています。navigator.updateAdInterestGroups() を繰り返し呼び出しても、レート制限期間（現在は 1 日）が経過するまでは何も行われません。

同じインタレスト グループの owner と name に対して navigator.joinAdInterestGroup() が再度呼び出される場合、レート制限はリセットされます。

# 自動更新

オークション用にロードされたすべてのインタレスト グループは、手動更新と同じレート制限が適用される上で、オークションの完了後に自動的に更新されます。

少なくとも 1 つのインタレスト グループがオークションに参加しているオーナーごとに、そのオーナーと一致するオリジンの iframe から navigator.updateAdInterestGroups() が呼び出されたかのように動作します。

# インタレスト グループの広告の指定

ads および adComponents オブジェクトには、広告クリエイティブの URL と、オプションで、入札時に使用できる任意のメタデータが含まれます。

以下に例を示します。

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

# generateBid()

biddingLogicUrl にあるインタレスト グループオーナーのスクリプトには、generateBid() 関数が含まれている必要があります。

売り手が navigator.runAdAuction() を呼び出すと、generateBid() 関数が広告の候補ごとに 1 回呼び出されます。つまり、インタレスト グループのオーナーが入札に招待されている場合、ブラウザがメンバーとなっているインタレスト グループごとに呼び出されます。

売り手は、navigator.runAdAuction() に渡されるオークション構成パラメーターに decisionLogicUrl を提供します。この URL のコードには、参加している各入札者によって生成された入札をスコアリングする scoreAd() 関数が含まれている必要があります。

買い手が提供する biddingLogicUrl のスクリプトには、generateBid() 関数が含まれている必要があります。

この関数は、候補広告ごとに 1 回呼び出されます。runAdAuction() は、関連付けられた入札とメタデータとともに各広告を個別にチェックしてから、数値の望ましさスコアを広告に割り当てます。

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

# 引数

generateBid() は次の引数を取ります。

³ browserSignals オブジェクトには次のプロパティがあります。

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

bid 値を計算するには、generateBid() のコードで関数のパラメーターのプロパティを使用できます。

以下に例を示します。

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() は、以下の 4 つのプロパティを持つオブジェクトを返します。

# leaveAdInterestGroup()

インタレスト グループのオーナーは、ブラウザをインタレスト グループから削除するよう要求できます。メンバーシップ リストからインタレスト グループを削除するのはブラウザです。

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

ユーザーがインタレスト グループの追加をブラウザに要求したサイトに戻った場合、インタレスト グループのオーナーは navigator.leaveAdInterestGroup() 関数を呼び出してブラウザにインタレスト グループの削除を要求できます。

広告のコードを使って、そのインタレスト グループに対してこの関数を呼び出すこともできます。

# よくある質問

# すべての Protected Audience API リファレンス

以下の API リファレンスガイドが提供されています。

• Protected Audience API の開発者ガイド。
• Protected Audience インタレストグループと入札生成に関する広告バイヤーガイド。
• Protected Audience 広告オークションに関する広告セラーガイド。
• オークション結果のレポートに関するガイド
• Protected Audience 広告オークションのレイテンシに関するベストプラクティス
• Protected Audience のトラブルシューティング

Protected Audience API の Explainer には、機能のサポートと制約に関する詳細が提供されています。