Protected Audience API オークションでリマーケティング リストに参加して入札するための買い手向け API ガイドとリファレンス。
この記事では、実験的な 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 のみです。
| プロパティ | 例 | 役割 |
|---|---|---|
owner |
https://dsp.example |
インタレスト グループ オーナーのオリジン。 |
name |
custom-bikes |
インタレスト グループの名前。 |
オプションのプロパティ
残りのプロパティはオプションです。
-
biddingLogicUrl1、2 _ - 例:
https://dsp.example/bid/custom-bikes/bid.js - 役割: ワークレットで実行される入札 JavaScript の URL。
-
biddingWasmHelperUrl1、2 _ - 例:
https://dsp.example/bid/custom-bikes/bid.wasm - 役割:
biddingLogicUrlから駆動される WebAssembly コードの URL。 -
dailyUpdateUrl - 例:
https://dsp.example/bid/custom-bikes/update - 役割: インタレスト グループの属性を更新する JSON を返す URL。（インタレスト グループを更新するをご覧ください。）
-
trustedBiddingSignalsUrl - 例:
https://dsp.example/trusted/bidding-signals - 役割: 入札者の信頼できるサーバーへの Key-Value リクエストのベース URL。
trustedBiddingSignalsKeys- 例:
['key1', 'key2' ...] - 役割: Key-Value の信頼できるサーバーへのリクエストのキー。
userBiddingSignals- 例:
{...} - 役割: オーナーが入札中に使用できる追加のメタデータ。
-
ads - 例:
[bikeAd1, bikeAd2, bikeAd3] - 役割: このインタレスト グループ向けにレンダリングされる可能性のある広告。
adComponents- 例:
[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] - 役割: 複数の部分で構成される広告のコンポーネント。
1 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.
2 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 を返すウェブサーバーを指定します。
これにより、グループのオーナーは、インタレスト グループの属性を定期的に更新できます。現在の実装では、次の属性を変更できます。
biddingLogicUrlbiddingWasmHelperUrltrustedBiddingSignalsUrltrustedBiddingSignalsKeysadspriority
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() は次の引数を取ります。
| 引数 | 役割 |
|---|---|
interestGroup |
広告の買い手によって渡されるオブジェクト。インタレスト グループは、dailyUpdateUrl で更新される場合があります。 |
auctionSignals |
売り手によって navigator.runAdAuction() に渡されるオークション構成引数のプロパティ。これにより、ページ コンテキスト（広告サイズやサイト運営者 ID など）、オークションの種類（ファースト プライスまたはセカンド プライス）、およびその他のメタデータに関する情報が提供されます。 |
perBuyerSignals |
売り手によって渡されるオークション構成引数のプロパティ。これにより、売り手が SSP であり、買い手のサーバーにリアルタイムの入札呼び出しを実行してレスポンスを返す場合、またはサイト運営者のページが買い手のサーバーに直接接続する場合、買い手のサーバーからページに関するコンテキスト シグナルを提供できます。その場合、買い手は、改ざんに対する保護として、generateBid() 内のこれらのシグナルの暗号署名を確認することを希望する場合があります。 |
trustedBiddingSignals |
キーがインタレスト グループの trustedBiddingSignalsKeys であり、その値が trustedBiddingSignals リクエストで返されるオブジェクト。 |
browserSignals3
|
ブラウザによって作成されたオブジェクトで、ページコンテキストに関する情報（現在のページの hostname など、売り手が偽造する可能性があるもの）やインタレスト グループ自体のデータ（グループが以前に落札したときの記録など、オンデバイスのフリークエンシー キャップを許可するためのデータ）が含まれる場合があります。 |
3 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 つのプロパティを持つオブジェクトを返します。
| プロパティ | 役割 |
|---|---|
ad |
売り手がこの入札または広告クリエイティブについて知ることを期待する情報など、広告に関する任意のメタデータ。売り手は、この情報をオークションおよび決定ロジックで使用します。 |
bid |
オークションに入力する数値入札。売り手は、さまざまな買い手の入札を比較できる立場にある必要があります。したがって、入札は、売り手が選択した単位で行う必要があります（例: 「1,000 単位の USD」)。入札額がゼロまたはマイナスの場合、このインタレスト グループは売り手のオークションにまったく参加しません。この仕組みにより、買い手は、広告が表示される場所と表示されない場所に関する広告主ルールを実装できます。 |
render |
この入札がオークションで落札された場合にクリエイティブをレンダリングするために使用される URL または URL のリスト。値は、インタレスト グループに対して定義されたいずれかの広告の `renderUrl` と一致する必要があります。 複数の部分で構成される広告の Explainer |
adComponents |
`navigator.joinAdInterestGroup()` に渡されるインタレスト グループ引数の adComponents プロパティから取得される、複数の部分で構成される広告の最大 20 個のコンポーネントのオプションリスト。 |
leaveAdInterestGroup()
インタレスト グループのオーナーは、ブラウザをインタレスト グループから削除するよう要求できます。メンバーシップ リストからインタレスト グループを削除するのはブラウザです。
navigator.leaveAdInterestGroup({
owner: 'https://dsp.example',
name: 'custom-bikes'
});
ユーザーがインタレスト グループの追加をブラウザに要求したサイトに戻った場合、インタレスト グループのオーナーは navigator.leaveAdInterestGroup() 関数を呼び出してブラウザにインタレスト グループの削除を要求できます。
広告のコードを使って、そのインタレスト グループに対してこの関数を呼び出すこともできます。
よくある質問
クリックによるフリークエンシー制御を実装するにはどうすればよいですか？
単純なフリークエンシー制御であれば、generateBid() 内の browserSignals の prevWins フィールドを使用できます。または、navigator.leaveAdInterestGroup() を呼び出して、広告がクリックされたときにユーザーのブラウザがインタレスト グループから外されるようにリクエストすることもできます。このようにすると以降の入札が阻止されるため、フリークエンシー
キャップの一種として機能します。
ファーストパーティ Cookie を使用してクリック情報を保存することもできます。広告がレンダリングされると、既存のインタレスト グループがユーザーの入札シグナルとしてのクリック データで上書きされます。ワークフローは次のようになります。
- ユーザーが、
advertiser.com/productにアクセスします。 - 広告主はファーストパーティ Cookie に「0 クリック」を書き込み、
joinAdInterestGroup({ ..., userBiddingSignals: { clicks: [] } })を呼び出します。 - ユーザーが後で広告をクリックすると、
advertiser.com/productに移動されます。 - 広告主はファーストパーティ Cookie のクリックデータを読み取って増分し、
joinAdInterestGroup({ userBiddingSignals: { clicks: ["1667499972"] } })を呼び出します。 以降の入札では、
userBiddingSignalsで利用可能なクリックデータを入札ロジックで使用できます。
ユーザーの最近の閲覧履歴を広告の推奨に使用するにはどうすればよいですか？
joinAdInterestGroup() を呼び出したサイトのユーザーの閲覧履歴は、userBiddingSignals で更新でき、オンデバイス入札中に使用できます。製品レベルの TURTLEDOVE の原案を参照してください。これには、推奨ユースケース採用のためのコア指標の影響に関する RTB House による分析が含まれています。
dailyUpdateUrl はインタレスト グループの属性を定期的に更新するメカニズムを提供していますが、この更新はユーザーの閲覧履歴に基づくものではありません。
グループオーナーあたり、最大いくつの単一ユーザーインタレスト グループが許可されていますか？
Chrome では、オーナーあたり最大 1,000 個のインタレスト グループ、および最大 1,000 個のインタレスト グループ オーナーを許可しています。これらはガードレールとしての役割を果たしており、通常の操作では到達することはありません。
𝑘-anon のしきい値を満たすインタレスト グループ広告を最大化するにはどうすればよいですか？
公開 Explainer に指摘されているように、1 つのインタレスト グループは、表示される可能性のある複数の広告を掲載できるため、そのグループには、最も優先される広告がしきい値を下回るたびに、「フォールバック広告」として機能する別の広告を再入札する機会が与えられます。つまり、𝑘 匿名性のしきい値を未だに下回っている小規模の専門的な広告でもオークションに参加することを選択でき、そのインタレスト グループには、より専門的な広告が十分な数のオーディエンスを獲得するまで、より一般的な広告にフォールバックする方法があるということです。
戦術的には、以下のことを考慮するとよいでしょう。
新しい広告が表示され始めるようにするには、その広告を表示したいケースへの入札を開始します。ほかに何も行う必要はありません。
新しい広告が 𝑘-anon ではない場合に使用するフォールバック広告を設定できます。フォールバック広告自体が 𝑘-anon ではないリスクがあるため、場合によっては最初からフォールバック広告のみで入札することを検討することもできます。フォールバックがしきい値を上回る状態を維持できる十分なレベルであれば、たとえばこれを 1% の確率で実行することができます。
最近、他の方法で機能する可能性についてのディスカッションがありました。このメカニズムで問題が起きるユースケースがある場合は、API を改善する方法についての公開ディスカッションに引き続き参加してください。
すべての Protected Audience API リファレンス
API リファレンス ガイドが提供されています。
- Protected Audience API のデベロッパー ガイド。
- Protected Audience のインタレスト グループと入札の生成に関する広告購入者向けガイド。
- Protected Audience の広告オークションに関する広告販売者向けガイド。
- オークション結果のレポートに関するガイド
- Protected Audience の広告オークションの遅延に関するベスト プラクティス
- Protected Audience のトラブルシューティング
Protected Audience API の解説では、機能のサポートと制約に関する詳細も説明しています。