FLEDGE API 開発者ガイド
この記事の対象者
この記事は、実験的な FLEDGE API の現在のイテレーションに関する技術リファレンスです。
FLEDGE APIは、提案の技術的な概要ではなく、用語集もあります。
FLEDGE デモでは、FLEDGE の基本的なデプロイのウォークスルーを説明します。
FLEDGE デモ動画では、デモコードがどのように動作するかを説明し、FLEDGE のデバッグに Chrome DevTools を使用する方法を示します。
FLEDGEとは
FLEDGE は、リマーケティングおよびカスタム オーディエンスのユースケースに対応するためのプライバシーサンドボックスの提案であり、サードパーティがサイトを跨いでユーザーのブラウジング行動を追跡できないように設計されています。この API は、ブラウザによるオンデバイス オークションを有効にし、ユーザーが以前にアクセスしたウェブサイトに関連する広告を選択します。
FLEDGE は、TURTLEDOVE ファミリの提案の中で Chromium に実装された最初の実験です。
以下の図は、FLEDGE のライフサイクルの概要を示しています(拡大版を表示)。
FLEDGE を試すには
FLEDGE デモ
広告主とサイト運営者のサイトにまたがる基本的な FLEDGE のデプロイのウォークスルーは、fledge-demo.glitch.me で入手できます。
デモ動画では、デモコードがどのように動作するかを説明し、FLEDGE のデバッグに Chrome DevTools を使用する方法を示します。
FLEDGE オリジントライアルに参加する
プライバシーサンドボックスの広告関連のオリジントライアルは、FLEDGE、Topics、およびAttribution Reporting API について、デスクトップの Chrome ベータ版 101.0.4951.26 以降で公開されています。
参加するには、オリジントライアル トークンに登録してください。
トライアルへの登録に成功したら、有効なトライアル トークンを提供するページで FLEDGE JavaScript API を試すことができます。たとえば、ブラウザに 1 つ以上のインタレストグループに参加するように依頼してから、広告オークションを実行して広告を選択し、表示することができます。
FLEDGE デモでは、FLEDGE デプロイの基本的なエンドツーエンドの例を説明しています。
FLEDGE API コードを実行するすべてのページにトライアルトークンを提供してください。
<head> のメタタグの場合:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
HTTP ヘッダーの場合:
Origin-Trial: TOKEN_GOES_HERE
プログラムでトークンを提供する場合:
const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);
インタレストグループ オーナーによる navigator.joinAdInterestGroup()
呼び出しなどの FLEDGE コードを実行する iframe は、そのオリジンと一致するトークンを提供する必要があります。
Proposed First FLEDGE Origin Trial Details(提案された最初の FLEDGE オリジントライアルの詳細)には、最初のトライアルの目標に関する詳細と、どの機能がサポートされているかが説明されています。
有効なトライアルトークンを提供するページであっても、すべてのユーザーがプライバシーサンドボックスの広告関連のオリジントライアルの対象となるわけではありません。
プライバシーサンドボックス広告関連 API をテストするにはその理由が説明されており、オリジントライアル機能を使用する前に使用可能かどうかを検出する方法(検出する必要があります)が示されています。
chrome://flags
または機能フラグでテストする
デスクトップの Chrome ベータ版 101.0.4951.26 以降で、1 人のユーザーに対して FLEDGE をテストできます。
chrome://flags/#privacy-sandbox-ads-apis
を有効にします。- コマンドラインからフラグを設定します。
iframe または Fenced Frame に広告を表示する
広告は、設定されているフラグに応じて、<iframe>
または <fencedframe>
にレンダリングできます。
<fencedframe>
を使用して広告をレンダリングするには:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
<iframe>
を使用して広告をレンダリングするには:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
BiddingAndScoringDebugReportingAPI
フラグを含めて、一時的なデバッグの落札/競り負けレポートメソッドを有効にします。
Run Chromium with flags には、コマンドラインから Chrome やその他の Chromium ベースブラウザを実行する際にフラグを設定する方法が説明されています。FLEDGE フラグの完全なリストは、Chromium Code Search から入手できます。
これは、初期テスト用の FLEDGE の進行中のバージョンです。これは、完全なもの、または最終的な実装を示すものと見なすべきではありません。FLEDGE の進捗状況とステータスは、定期的な WICG 会議で議論されます。
2021 年 5 月 12 日の WICG 会議の議事録には、現在の実装でサポートされているものとサポートされていないものに関する詳細が記載されています。
プライバシーサンドボックスのタイムラインには、FLEDGE およびその他のプライバシーサンドボックスの提案の実装タイミングに関する情報が提供されています。
最新バージョンの Chrome でサポートされている機能
FLEDGE は、FLEDGE 提案の次の機能をテストする最初の実験として、Chromium で機能フラグの使用によって利用できるようになっています。
- インタレストグループ: 広告の入札とレンダリングを構成するための関連付けられたメタデータとともに、ブラウザによって保存されます。
- バイヤー(DSP または広告主)によるオンデバイス入札: 保存されているインタレストグループとセラーからのシグナルに基づきます。
- セラー(SSP またはサイト運営者)によるオンデバイス広告の選択: バイヤーからのオークション入札とメタデータに基づきます。
- 一時的に緩和されたバージョンの Fenced Frames での広告レンダリング: 広告のレンダリングが許可されたネットワークアクセスとロギング。
API Explainer には、機能のサポートと制約に関する詳細が提供されています。
インタレストグループの権限
FLEDGE の現在の実装のデフォルトでは、クロスドメイン iframe からでも、ページ内のどこからでも joinAdInterestGroup()
を呼び出すことができるようになっています。将来的には、サイト所有者がクロスドメイン iframe の権限ポリシーを調整する時間ができたら、Explainer で説明されているように、クロスドメイン iframe からの呼び出しを禁止する予定です。
Key/Value サービス
FLEDGE 広告オークションの一部として、ブラウザは、単純なキーと値のペアを返すKey/Value サービスにアクセスして、残りのキャンペーン予算などの情報を広告バイヤーに提供できます。FLEDGE 提案は、このサーバーが「イベントレベルのログ記録を実行しないこと、およびこれらのリクエストに基づくその他の副作用がないこと」を義務付けています。
FLEDGE Key/Value サービスコードは、Privacy Sandbox GitHub リポジトリで提供されるようになりました。このサービスは、Chrome および Android の開発者が使用できます。ステータスの更新については、お知らせのブログ記事をご覧ください。API Explainer および Trust Model Explainer から FLEDGE Key/Value サービスの詳細をご覧ください。
初期テストでは、 「Bring Your Own Server」モデルが使用されます。長期的には、アドテックはリアルタイムデータを取得するために、信頼できる実行環境で実行されるオープンソースの FLEDGE Key/Value サービスを使用する必要があります。
エコシステムがテストするのに十分な時間を確保するために、サードパーティの Cookie が廃止されるまでは、オープンソースの Key/Value サービスまたは TEE の使用が必要になるとは考えていません。この移行が行われる前に、開発者がテストと採用を開始できるのに十分な通知を行う予定です。
機能サポートの検出
API を使用する前に、API がブラウザでサポートされており、ドキュメントで使用できるかどうかを確認してください。
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
現在のページでの機能のサポートは、API が使用できることを保証するものではありません。ユーザーがブラウザの設定で API を無効にしたか、API を使用できないように他の設定をしている可能性があります。ユーザーのプライバシーを保護するために、これをプログラムで確認する方法はありません。
FLEDGE をオプトアウトするには
サイト所有者または個人ユーザーは、FLEDGE API へのアクセスをブロックできます。
サイトによるアクセス制御
FLEDGE では、最終的に、FLEDGE 機能を利用できるようにするために、サイトがアクセス許可ポリシーを設定するように要求する意向です。これにより、任意の第三者はサイトに知られることなく API を使用できないようにすることができます。ただし、最初のオリジントライアル中のテストを実施しやすくするために、この要件はデフォルトで免除されます。テスト期間中に FLEDGE 機能を明示的に無効にしたいサイトは、関連する権限ポリシーを使用してアクセスをブロックできます。
FLEDGE の権限ポリシーには、個別に設定できる 2 つのポリシーがあります。
join-ad-interest-group
: ブラウザをインタレストグループに追加する機能を有効/無効にします。run-ad-auction
: オンデバイスオークションを実行する機能を有効または無効にします。
FLEDGE API へのアクセスは、HTTP レスポンスヘッダーで次のアクセス許可ポリシーを指定することにより、ファーストパーティのコンテキストで完全に無効にすることができます。
Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()
次の allow
属性を iframe 要素に追加することで、iframe での API の使用を無効にすることができます。
<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>
Proposed First FLEDGE Origin Trial Permissions-Policy セクションに詳細が記載されています。
ユーザーのオプトアウト
ユーザーは、次のいずれかの仕組みを使用して、FLEDGE API およびその他のプライバシーサンドボックス機能へのアクセスをブロックできます。
- Chrome 設定で 設定 > セキュリティとプライバシー > プライバシーサンドボックス に移動し、プライバシーサンドボックスのトライアルを無効にします。これには
chrome://settings/privacySandbox
からもアクセスできます。 - Chrome 設定で 設定 > セキュリティとプライバシーに移動し、サードパーティの Cookie を無効にします。
chrome://settings/cookies
で、Cookie とその他のサイト データを「サードパーティの Cookie をブロックする」または「すべての Cookie をブロックする」に設定します。- シークレットモードを使用します。
FLEDGE Explainer には、API の設計要素に関する詳細が説明されています。また、API がプライバシーの目標をどのように満たそうとしているのかが記載されています。
FLEDGE ワークレットのデバッグ
Chrome Canary 98.0.4718.0 より、Chrome DevTools 内で FLEDGE ワークレットをデバッグできます。
最初のステップは、[ソース] パネルの [イベント リスナー ブレークポイント] ペインの新しいカテゴリを介してブレークポイントを設定することです。
ブレークポイントがトリガーされると、ワークレット スクリプトの最上位にある最初のステートメントの前で実行が一時停止されます。通常のブレークポイントまたはステップ コマンドを使用して、入札/スコアリング/レポート機能自体にアクセスできます。
ライブ ワークレット スクリプトも [スレッド] パネルの下に表示されます。
一部のワークレットは並行して実行される可能性があるため、複数のスレッドがそこで「一時停止」状態になる可能性があります。スレッド リストを使用してスレッドを切り替え、必要に応じてスレッドを再開または詳細に調べることができます。
FLEDGE イベントを観察する
Chrome DevTools の [アプリケーション] パネルから、FLEDGE インタレスト グループとオークション イベントを観察できます。
FLEDGE が有効になっているブラウザで FLEDGE のデモショッピングサイトにアクセスすると、DevTools に join
イベントに関する情報が表示されます。
これで、FLEDGE が有効になっているブラウザでFLEDGE のデモサイト運営者サイトにアクセスすると、DevTools は bid
イベントと win
イベントに関する情報を表示します。
サイトに移動したときに DevTools が開いていなかった場合は、ページを更新して FLEDGE イベントを表示する必要があります。
FLEDGE API の仕組み
この例では、ユーザーがカスタム バイク メーカーのウェブサイトを閲覧した後、ニュースサイトにアクセスすると、そのバイク メーカーの新しい自転車の広告が表示されます。
この記事で説明されているすべての機能が、現在 Chrome でテストされている FLEDGE API のバージョンに実装されている(または完全に実装されている)わけではありません。機能フラグを使用したテストでは、 機能フラグを使用してコマンドラインから実行される Chrome で現在どの FLEDGE 機能をテストできるかについて説明されています。
FLEDGE の機能は、実装作業が続くにつれて徐々に追加されることを期待しています。API がオリジントライアルの段階に達すると、定期更新のリストで実装済みの部分とまだ進行中の部分をお知らせします。
1. ユーザーが広告主のサイトにアクセスする
ユーザーがカスタム バイク メーカー(この例では広告主)のウェブサイトにアクセスし、手作りのスチール バイクの製品ページにしばらくアクセスしたとします。これにより、バイク メーカーはリマーケティングの機会を得ることができます。
デマンドサイド プラットフォーム(DSP)は、広告購入の自動化に使用されるアドテック サービスです。 DSP は、広告主がさまざまなサイト運営者サイトで広告インプレッションを購入するために使用されます。サイト運営者は、アドエクスチェンジと呼ばれるマーケットプレイスを通じて広告枠を売りに出し、DSP は、広告主が購入するのに最も意味のある利用可能な広告インプレッションをプログラムで決定します。
サプライサイド プラットフォーム(SSP)は、広告枠の販売を自動化するために使用されるアドテック サービスです。SSP を使用すると、サイト運営者は広告枠(広告が表示される空の矩形)を複数のアドエクスチェンジ、DSP、およびネットワークにオファーできます。これにより、幅広い潜在的なバイヤーが広告スペースに入札できるようになります。
2. ユーザーのブラウザがインタレストグループを追加するよう求められる
Explainer のセクション: ブラウザがインタレストグループを記録する
広告主のデマンド サイド プラットフォーム(DSP)(または広告主自体)は、 navigator.joinAdInterestGroup()
を呼び出して、ブラウザがメンバーであるグループのリストにインタレストグループを追加するようブラウザに要求します。この例では、グループの名前は custom-bikes
で、所有者は dsp.example
です。インタレストグループのオーナー(この場合は DSP)は、ステップ 4で説明した広告オークションのバイヤーになります。インタレストグループのメンバーシップは、ブラウザによってユーザーのデバイスに保存され、ブラウザ ベンダーや他の誰とも共有されません。
joinAdInterestGroup()
の呼び出し元コンテキストのオリジンは、インタレストグループのオーナーのオリジンと一致する必要があるため、joinAdInterestGroup()
は、インタレストグループのオーナーのオリジンと現在のドキュメントのオリジンが一致しない限り(たとえば、独自のインタレストグループを持つウェブサイト)、iframe から呼び出す必要があります。
runAdAuction
には同じ要件がないため、<script> タグから runAdAuction()
を呼び出すと、おそらくクロスオリジン iframe よりもはるかにパフォーマンスが向上します。
joinAdInterestGroup()
には以下からの許可が必要です。
- アクセスされているサイト
- インタレストグループのオーナー
例: malicious.example
が dsp.example
の許可なしにオーナーとして dsp.example
を使用して joinAdInterestGroup()
を呼び出すことが可能であってはいけません。
アクセスされているサイトからの許可
同じオリジン: デフォルトでは、アクセスされているサイトと同じオリジン、つまり、現在のページのトップレベル フレームと同じオリジンからの joinAdInterestGroup()
呼び出しに対して許可が暗黙的に付与されます。サイトは、FLEDGE のアクセス許可ポリシー ヘッダーの join-ad-interest-group
ディレクティブを使用して、joinAdInterestGroup()
呼び出しを無効にすることができます。
クロスオリジン: 現在のページとは異なるオリジンからの joinAdInterestGroup()
の呼び出しは、アクセスされているサイトがクロスオリジン iframe からの joinAdInterestGroup()
の呼び出しを許可するアクセス許可ポリシーを設定している場合にのみ成功します。
FLEDGE の現在の実装のデフォルトでは、クロスオリジン iframe からでも、ページ内のどこからでも joinAdInterestGroup()
を呼び出すことができます。将来、サイト所有者がアクセス許可ポリシーを調整する時間ができたら、FLEDGE の Explainer で説明されているように、クロスオリジン iframe からの呼び出しをデフォルトで禁止する予定です。
インタレストグループのオーナーからの許可
インタレストグループのオーナーのアクセス許可は、インタレストグループのオーナーと同じオリジンを持つ iframe から joinAdInterestGroup()
を呼び出すことによって暗黙的に付与されます。たとえば、dsp.example
iframe は、 dsp.example
が所有するインタレストグループに対して joinAdInterestGroup()
を呼び出すことができます。
提案は、joinAdInterestGroup()
がオーナーのドメインのページまたは iframe で実行されるか、.well-known
URL のリストを使用して提供される他のドメインに委譲されることです。
navigator.joinAdInterestGroup() の使用
API の使用方法の例を次に示します。
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 日です。連続して呼び出すと、以前に保存された値が上書きされます。
FLEDGE API メソッドのパラメーターとして使用されるすべての URL は、安全なオリジンからのものである必要があります。すべてのリソースは、HTTPS URL 経由で提供される必要があります。ローカル開発での HTTPS の使用方法には、FLEDGE をローカルで実行するときにこれをどのように行うかが説明されています。
さらに、biddingLogicUrl
、decisionLogicUrl
、trustedBiddingSignals
にはすべて、X-Allow-FLEDGE: true
HTTP レスポンスヘッダーが必要です。
インタレストグループのプロパティ
プロパティ | 必須 | 例 | 役割 |
---|---|---|---|
owner | 必須 | 'https://dsp.example' | インタレストグループ オーナーのオリジン。 |
name | 必須 | 'custom-bikes' | インタレストグループの名前。 |
biddingLogicUrl ** | オプション* | 'https://dsp.example/bid/custom-bikes/bid.js' | ワークレットで実行される入札 JavaScript の URL。 |
biddingWasmHelperUrl ** | オプション* | '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] | 複数のピースで構成される広告のコンポーネント。 |
* owner
と name
を除くすべてのプロパティはオプションです。 biddingLogicUrl
および ads
プロパティはオプションですが、オークションに参加するには必須です。これらのプロパティを使用せずにインタレストグループを作成するユースケースもあるかもしれません。たとえば、インタレストグループ オーナーがまだ実行していないキャンペーンもしくは将来的な他の用途のインタレストグループにブラウザを追加したいと考える可能性があります。または、一時的に広告バジェットが不足している可能性も考えられます。
** FLEDGE の現在の実装では、biddingLogicUrl
、biddingWasmHelperUrl
、dailyUpdateUrl
、trustedBiddingSignalsUrl
にはオーナーとして同じオリジンを持つ必要があります。これは長期的な制約ではない可能性があり、ads
と adComponents
の URL にはそのような制約はありません。
インタレストグループの属性を更新する
dailyUpdateUrl
は、navigator.joinAdInterestGroup()
に渡されるインタレストグループ オブジェクトに対応してインタレストグループ プロパティを定義する JSON を返すウェブサーバーを指定します。これにより、グループのオーナーがインタレストグループの属性を定期的に更新する仕組みが提供されます。現在の実装では、次の属性を変更できます。
biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority
JSON で指定されていないフィールドは上書きされず、JSON で指定されたフィールドのみが更新されますが、navigator.joinAdInterestGroup()
を呼び出すと、既存のインタレストグループが上書きされます。
更新はベストエフォートであり、次の状況では失敗する可能性があります。
- ネットワークリクエストのタイムアウト(現在 30 秒)。
- その他のネットワーク障害。
- JSON 解析の失敗。
更新に連続して長い時間が費やされた場合には、更新がキャンセルされることもありますが、これによりキャンセルされた(残りの)更新にレート制限が課されることはありません。更新は、1 日あたり最大 1 回にレート制限されています。ネットワーク エラーが原因で失敗した更新は 1 時間後に再試行され、インターネットからの切断が原因で失敗した更新は再接続後にすぐに再試行されます。
手動更新
現在のフレームのオリジンが所有するインタレストグループの更新は、navigator.updateAdInterestGroups()
を介して手動でトリガーできます。頻繁な更新はレート制限によって防止されています。navigator.updateAdInterestGroups()
を繰り返し呼び出しても、レート制限期間(現在は 1 日)が経過するまで何も起こりません。navigator.joinAdInterestGroup()
が同じインタレストグループの owner
と name
に対して再度呼び出されると、レート制限がリセットされます。
自動更新
オークションにロードされたすべてのインタレストグループは、オークションの完了後に自動的に更新されますが、手動更新と同じレート制限が適用されます。オークションに参加しているインタレストグループが少なくとも 1 つあるオーナーごとに、そのオーナーと一致するオリジンを持つ iframe から navigator.updateAdInterestGroups()
が呼び出されたかのように動作します。
インタレストグループの広告を指定する
ads
および adComponents
オブジェクトには、広告クリエイティブの URL と、オプションで、入札時に使用できる任意のメタデータが含まれます。以下に例を示します。
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // オプション
}
バイヤーの入札方法
インタレストグループのオーナーが提供する biddingLogicUrl
のスクリプトには、generateBid()
関数が含まれている必要があります。広告スペースのセラーが navigator.runAdAuction()
を呼び出す際にインタレストグループのオーナーが入札に招待されていれば、ブラウザがメンバーであるインタレストグループごとに generatedBid()
関数が 1 回呼び出されます。つまり、generateBid()
は候補広告ごとに 1 回呼び出されます。セラーは、navigator.runAdAuction()
に渡されるオークション構成パラメーターで decisionLogicUrl
プロパティを提供します。この URL のコードには、generateBid()
によって返される各入札をスコアリングするために、オークションの各入札者に対して実行される scoreAd()
関数を含める必要があります。
biddingWasmHelperUrl
プロパティはオプションですが、入札者は、biddingLogicUrl
によって提供される JavaScript 関数から駆動されるように、JavaScript ではなく WebAssembly で計算コストの高いサブルーチンを提供できます。指定する場合は、application/wasm mimetype
で配信される WebAssembly バイナリを指す必要があります。対応する WebAssembly.Module
は、ブラウザによって generateBid()
関数で使用できるようになります。
広告スペースのバイヤーが提供する、biddingLogicUrl
のスクリプトには、generateBid()
関数が含まれている必要があります。この関数は、候補広告ごとに 1 回呼び出されます。runAdAuction()
は、関連付けられた入札とメタデータとともに各広告を個別にチェックしてぁら、数値の望ましさスコアを広告に割り当てます。
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
...
return {
ad: adObject,
bid: bidValue,
render: renderUrl,
adComponents: [adComponentRenderUrl1, ...]
};
}
generateBid()
は次の引数を取ります。
interestGroup
広告バイヤーによってjoinAdInterestGroup()
に渡されるオブジェクト。(インタレストグループは、dailyUpdateUrl
を介して更新される場合があります。)auctionSignals
広告スペースのセラーによってnavigator.runAdAuction()
に渡されるオークション構成引数のプロパティ。これにより、ページ コンテキスト(広告サイズやサイト運営者 ID など)、オークションの種類(ファーストプライスまたはセカンドプライス)、およびその他のメタデータに関する情報が提供されます。perBuyerSignals
auctionSignals
と同様に、セラーによってnavigator.runAdAuction()
に渡されるオークション構成引数のプロパティ。これにより、セラーが SSP であり、バイヤーのサーバーにリアルタイムの入札呼び出しを実行してレスポンスを返す場合、またはサイト運営者のページがバイヤーのサーバーに直接接続する場合、バイヤーのサーバーからページに関するコンテキストシグナルを提供できます。その場合、バイヤーは、改ざんに対する保護として、generateBid() 内のこれらのシグナルの暗号署名を確認することを希望する場合があります。trustedBiddingSignals
キーがインタレストグループのtrustedBiddingSignalsKeys
であり、その値がtrustedBiddingSignals
リクエストで返されるオブジェクト。browserSignals
ブラウザによって作成されたオブジェクトで、ページコンテキストに関する情報(現在のページのhostname
など、セラーが偽造する可能性があるもの)やインタレストグループ自体のデータ(グループが以前に落札したときの記録など、オンデバイスのフリークエンシーキャップを許可するためのデータ)が含まれる場合があります。
browserSignals
オブジェクトには次のプロパティがあります。
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
joinCount: 3,
bidCount: 17,
prevWins: [[time1,ad1],[time2,ad2],...],
wasmHelper: ... /* インタレストグループの biddingWasmHelperUrl に基づく WebAssembly.Module オブジェクト */
dataVersion: 1, /* バイヤーの Key/Value サービスレスポンスの Data-Version 値 */
}
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 のリスト。(API の Explainer で、複数のピースで構成された広告を参照してください。)値は、インタレストグループに対して定義された広告の 1 つのrenderUrl
と一致する必要があります。adComponents
navigator.joinAdInterestGroup()
に渡されるインタレストグループ引数のadComponents
プロパティから取得される、複数のピースで構成される広告の最大 20 個のコンポーネントのオプション リスト。
インタレストグループからの除外をブラウザに求める
インタレストグループのオーナーは、ブラウザをインタレストグループから削除するよう要求できます。言い換えれば、ブラウザは、メンバーであるグループのリストからインタレストグループを削除するように求められます。
navigator.leaveAdInterestGroup({
owner: 'https://dsp.example',
name: 'custom-bikes'
});
ユーザーがインタレストグループの追加をブラウザに要求したサイトに戻った場合、インタレストグループのオーナーは navigator.leaveAdInterestGroup()
関数を呼び出してブラウザにインタレストグループの削除を要求できます。広告のコードを使って、そのインタレストグループに対してこの関数を呼び出すこともできます。
3. ユーザーが広告スペースを販売するサイトにアクセスする
後になって、ユーザーは広告スペースを販売するサイト(この例ではニュースサイト)にアクセスします。このサイトには広告枠があり、リアルタイム入札を使用してプログラムで販売しています。
FLEDGE 提案の Explainer には、主に以下の 3 つの役割が説明されています。
- 広告主: 商品を宣伝するために料金を支払うサイト。この例では、カスタム バイク メーカーです。
- サイト運営者: この例にあるオンライン ニュースサイトなど、広告スペースを販売するサイト。広告スペースを販売しているサイトの多く(すべてではない)は、コンテンツパブリッシャーです。
- セラー: 広告オークションを運営する当事者(次のステップ)。ほとんどのサイト運営者は、SSP などのアドテックサービスを使用して、広告枠の販売を最適化しています。
4. ブラウザで広告オークションが実行される
Explainer のセクション: セラーがオンデバイスオークションを実行する
広告オークションは、サイト運営者の SSP またはサイト運営者自身によって実行される可能性があります。オークションの目的は、現在のページで使用可能な単一の広告スロットに最も適した広告を選択することです。オークションでは、広告スペースのバイヤーと Key/Value サービスのセラーからのデータとともに、ブラウザがメンバーであるインタレストグループが考慮されます。
広告スペースのセラーは、navigator.runAdAuction()
を呼び出して、ユーザーのブラウザに広告オークションを開始するよう要求します。
例えば以下のようにします。
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
runAdAuction()
は、広告オークションの結果を表す URN(urn:uuid:<something>
)に解決される promise を返します。これは、レンダリングのために Fenced Frame に渡された場合にのみ、ブラウザによってデコードできます。したがってサイト運営者のページは、落札した広告を検査できません。
joinAdInterestGroup()
の呼び出し元コンテキストのオリジンは、インタレストグループのオーナーのオリジンと一致する必要があるため、joinAdInterestGroup()
は、インタレストグループのオーナーのオリジンと現在のドキュメントのオリジンが一致しない限り(たとえば、独自のインタレストグループを持つウェブサイト)、iframe から呼び出す必要があります。
runAdAuction
には同じ要件がないため、<script> タグから runAdAuction()
を呼び出すと、おそらくクロスオリジン iframe よりもはるかにパフォーマンスが向上します。
decisionLogicUrl
スクリプトは、関連する入札とメタデータとともに個々の広告を 1 つずつ検討し、数値的な望ましさスコアを割り当てます。
auctionConfig
のプロパティ
プロパティ | 必須 | 例 | 役割 |
---|---|---|---|
seller | 必須 | 'https://ssp.example' | セラーのオリジン |
decisionLogicUrl | 必須 | 'https://ssp.example/auction-decision-logic.js' | オークション ワークレット JavaScript の URL。 |
trustedScoringSignalsUrl | オプション | 'https://ssp.example/scoring-signals' | セラーの信頼できるサーバーの URL。 |
interestGroupBuyers* | 必須 | ['https://dsp.example', 'https://buyer2.example', ...] | オークションへの入札を依頼されたすべてのインタレストグループのオーナーのオリジン。 |
auctionSignals | オプション | {...} | ページのコンテキスト、オークションの種類などに関するセラー情報。 |
sellerSignals | オプション | {...} | サイト運営者の設定、コンテキスト広告リクエストの作成などに基づく情報。 |
sellerTimeout | オプション | 100 | セラーの scoreAd() スクリプトの最大実行時間(ミリ秒)。 |
perBuyerSignals | オプション | {'https://dsp.example': {...},<br>
'https://another-buyer.example': {...},<br>
...} | 特定のバイヤーごとのページに関する、それぞれのサーバーから得るコンテキストシグナル。 |
perBuyerTimeouts | オプション | 50 | 特定のバイヤーの generateBid() スクリプトの最大実行時間(ミリ秒)。 |
componentAuctions | オプション | [{'seller': 'https://www.some-other-ssp.com',<br>
'decisionLogicUrl': ..., ...},<br>
...] | コンポーネント オークションの追加設定。 |
* セラーは、interestGroupBuyers: '*'
を指定することで、すべてのインタレストグループが入札できるようにすることができます。すると、インタレストグループのオーナーが含まれていること以外の基準に基づいて、広告が承認または拒否されます。たとえば、セラーは広告クリエイティブをレビューして、ポリシーへの準拠を確認することがあります。
** additionalBids
は、FLEDGE の現在の実装ではサポートされていません。詳細については、FLEDGE Explainer のオークション参加者セクションをお読みください。
広告の選択方法
decisionLogicUrl
のコード(runAdAuction()
に渡されるオークション構成オブジェクトのプロパティ)に、scoreAd()
関数が含まれている必要があります。これは、広告の望ましさを判断するために、広告ごとに 1 回実行されます。
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
scoreAd()
は次の引数を取ります。
adMetadata
バイヤーが提供する任意のメタデータ。bid
数値による入札値。auctionConfig
navigator.runAdAuction()
に渡されるオークション構成オブジェクト。trustedScoringSignals
オークション時にセラーの信頼できるサーバーから取得された値で、広告に対するセラーの意見を表します。browserSignals
ブラウザが認識し、セラーのオークション スクリプトが検証する可能性のある情報を含む、ブラウザによって構築されたオブジェクト。
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}
オークションが始まる前に、セラーは利用可能な広告スロットに最適なコンテキスト広告を見つけます。その scoreAd()
ロジックには、コンテキストの落札者に勝てない広告を拒否するロジックが含まれます。
5. セラーと参加するバイヤーが、Key/Value サービスからリアルタイム データを受け取る
Explainer のセクション: FLEDGE Key/Value サービスからリアルタイムデータを取得する。
広告オークション中、広告スペースのセラーは、navigator.runAdAuction()
に渡されるオークション構成引数の trustedScoringSignalsUrl
プロパティと、オークションのすべてのインタレストグループの ads
フィールドと adComponents
フィールドのすべてのエントリの renderUrl
プロパティのキーを使用して Key/Value サービスにリクエストを行うことにより、特定の広告クリエイティブに関するリアルタイムデータを取得できます。
同様に、広告スペースのバイヤーは、navigator.joinAdInterestGroup()
に渡されるインタレストグループ引数の trustedBiddingSignalsUrl
プロパティと trustedBiddingSignalsKeys
プロパティを使用して、Key/Value サービスからリアルタイムデータをリクエストできます。
runAdAuction()
が呼び出されると、ブラウザは各広告バイヤーの信頼できるサーバーにリクエストを送信します。リクエストの URL は以下のようになります。
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- ベース URL は
trustedBiddingSignalsUrl
から取得されます。 hostname
はブラウザによって提供されます。keys
の値はtrustedBiddingSignalsKeys
から取得されます。
このリクエストへのレスポンスは、各キーの値を提供する JSON オブジェクトです。
FLEDGE をテストするための現在の初期実験段階では、trustedBiddingSignalsUrl
はインタレストグループのオーナーと同じオリジンを持つ必要があります。インタレストグループのプロパティと Bring Your Own Server を参照してください。
6. 落札した広告が表示される
Explainer のセクション: ブラウザが落札者の広告をレンダリングする
前に説明したように、runAdAuction()
によって返される promise は、レンダリングするために Fenced Frame に渡される URN に解決され、サイトは落札した広告を表示します。
7. オークション結果が報告される
Explainer のセクション: イベントレベルのレポート(現時点でのレポート)
長期的には、要約レポート APIを使用して、ブラウザがセラーとバイヤーのオークション結果をレポートできるようにすることを計画しています。一時的なイベントレベルのレポートの仕組みとして、セラー用に reportResult()
を実装し、落札者用に reportWin()
を実装するコードは、sendReportTo()
関数を呼び出すことができます。これはオークションの完了後に取得される URL を表す文字列を引数として取ります。これにより、レポートされるイベントレベルの情報が暗号化されます。
セラーによる結果の報告
Explainer のセクション: セラーがレンダリングについて報告する
decisionLogicUrl
で提供されるセラーの JavaScript(scoreAd()
でも提供)には、オークションの結果を報告するための reportResult()
関数を含めることができます。
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
この関数には以下の引数が渡されます。
auctionConfig
navigator.runAdAuction()
に渡されるオークション構成オブジェクト。browserSignals
オークションに関する情報を提供するブラウザによって作成されるオブジェクト。以下に例を示します。{
'topWindowHostname': 'publisher.example',
'interestGroupOwner': 'https://dsp.example',
'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
'bid:' <bidValue>,
'desirability': <winningAdScore>
}
この関数の戻り値は、落札者の reportWin()
関数の sellerSignals
引数として使用されます。
落札者による結果の報告
Explainer のセクション: バイヤーがレンダリングと広告イベントについて報告する
落札者の JavaScript(generateBid()
も提供)には、オークションの結果を報告するための reportWin()
関数を含めることができます。
reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
...
}
Chrome の FLEDGE の現在の実装では、reportWin()
が定義されていない場合に警告が表示されます。
この関数には以下の引数が渡されます。
auctionSignals
とperBuyerSignals
落札者のgenerateBid()
に渡されるのと同じ値。sellerSignals
reportResult()
の戻り値。これにより、バイヤーに情報を渡す機会がセラーに与えられます。browserSignals
オークションに関する情報を提供するブラウザによって作成されるオブジェクト。以下に例を示します。{
'topWindowHostname': 'publisher.example',
'seller': 'https://ssp.example',
'interestGroupOwner': 'https://dsp.example',
'interestGroupName': 'custom-bikes',
'renderUrl': 'https://cdn.example/winning-creative.wbn',
'bid:' <bidValue>
}
一時的な勝敗レポートの実装
Chrome では、暫定的に 2 つの方法でオークションの勝敗をレポートできます。
forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()
これらのメソッドはそれぞれ、オークションの完了後に取得する URL を引数として取ります。scoreAd()
と generateBid()
の両方で、異なる URL 引数を使用して何度も呼び出すことができます。
Chrome は、オークションが完了するまで実行された場合にのみ、デバッグの勝敗レポートを送信します。オークションがキャンセルされた場合(新しいナビゲーションなどが原因で)、レポートは生成されません。
これらのメソッドは、Chrome で chrome://flags/#privacy-sandbox-ads-apis
が有効になっている場合にデフォルトで使用できます。ただし、FLEDGE を有効にするコマンドライン フラグを使用して Chrome を実行している場合は、BiddingAndScoringDebugReportingAPI
フラグを含めて、メソッドを明示的に有効にする必要があります。フラグが有効になっていない場合、メソッドは引き続き使用できますが、何も起こりません。
8. 広告クリックが報告される
Fenced Frame にレンダリングされた広告のクリックが報告されます。これがどのように機能するかについて詳しくは、Fenced Frames 広告のレポートを参照してください。
以下の図は、FLEDGE の広告オークションの各段階の概要を示しています(拡大版を表示)。
FLEDGE と TURTLEDOVE の違い
FLEDGE と TURTLEDOVE の違い
FLEDGE は、TURTLEDOVE ファミリの提案の中で Chromium に実装された最初の実験です。
FLEDGE は、TURTLEDOVE の高レベルの原則に従います。一部のオンライン広告は、以前に広告主または広告ネットワークとやり取りしたことのある潜在的に関心のある人に広告を表示することに基づいています。これまで、これは広告主がウェブサイトをブラウジングする際に特定の人物を認識することで機能してきました。これが、今日のウェブのプライバシーに関する主な懸念事項です。
TURTLEDOVE の取り組みは、このユースケースに対処するための新しい API を提供すると同時に、プライバシーに関する以下のような重要な進化を提供することにあります。
- 広告主が考えるユーザーの興味についての情報を、広告主ではなくブラウザが保持する。
- 広告主は興味に基づいて広告を配信できますが、その興味を個人に関する他の情報(特に、そのユーザーやアクセスしているページなど)と組み合わせることはできません。
FLEDGE は、TURTLEDOVE と、API を使用する開発者により良いサービスを提供するための変更に関する関連提案のコレクションから生まれました。
- SPARROW: Criteo は、信頼できる実行環境(TEE)で実行される(「ゲートキーパー」)サービスモデルの追加を提案しました。 FLEDGE には、リアルタイムのデータ検索と集計レポートのための、より限定された TEE の使用が含まれます。
- NextRoll の TERN と Magnite の PARRROT の提案には、オンデバイス オークションにおけるバイヤーとセラーのさまざまな役割が説明されています。FLEDGE の広告入札・スコア付けフローは、この作業に基づいています。
- RTB House の結果ベースおよびプロダクトレベルの TURTLEDOVE の変更により、匿名モデルとオンデバイス オークションのパーソナライズ機能が改善されました。
- PARAKEET は、ブラウザとアドテック プロバイダーの間の TEE で実行されているプロキシサーバーに依存して広告要求を匿名化し、プライバシーのプロパティを強制する、TURTLEDOVE のような広告サービスに対する Microsoft の提案です。FLEDGE は、このプロキシモデルを採用していません。PARAKEET と FLEDGE の JavaScript API を連携させ、両方の提案の最良の機能をさらに組み合わせる将来の作業をサポートします。
FLEDGE はまだ、ユーザーがどの広告を見たかをウェブサイトの広告ネットワークが学習できないようにしていません。今後、よりプライベートになるように API を変更する予定です。
利用可能なブラウザ構成
利用可能なブラウザ構成
ユーザーは、chrome://settings/privacySandbox の最上位の設定を有効または無効にすることで、Chrome のプライバシーサンドボックス トライアルへの参加を調整できます。初期のテストでは、ユーザーはこの高レベルのプライバシーサンドボックス設定を通じて FLEDGE をオプトアウトできます。Chrome では、ユーザーがアクセスしたウェブサイト全てで、自分が追加されたインタレストグループのリストを表示および管理できるようにする予定です。プライバシーサンドボックスのテクノロジー自体と同様に、ユーザー設定は、ユーザー、規制当局などからのフィードバックによって進化する可能性があります。
テストとフィードバックに基づいて、FLEDGE の提案が進むにつれて、Chrome で利用可能な設定を更新し続けます。将来的には、FLEDGE と関連データを管理するためのより詳細な設定を提供する予定です。
ユーザーがシークレットモードで閲覧している場合、API 呼び出し元はグループ メンバーシップにアクセスできません。また、ユーザーがサイトデータを消去すると、メンバーシップが削除されます。
エンゲージメントとフィードバックの共有
- GitHub: 提案を読み、質問を投稿したり、ディスカッションを閲覧したりできます。
- W3C: Improving Web Advertising Business Group で業界のユースケースについて議論できます。
- 開発者サポート: Privacy Sandbox Developer Support リポジトリでは、質問したり、ディスカッションに参加したりできます。
- FLEDGE メーリング リスト: fledge-api-announce では、API に関するお知らせと更新を配信します。
- FLEDGE の定例会議にご参加ください(隔週)。どなたでも参加できますが、参加するにはまず WICG に参加してください。積極的に参加するのでも、聞くだけでも構いません!
- プライバシーサンドボックスのフィードバックフォームを使用すると、公開フォーラムの外で Chrome チームと非公開でフィードバックを共有できます。
サポートを受ける
ユーザーの実装、デモ、またはドキュメントについて質問するには、以下の方法を利用できます。
- privacy-sandbox-dev-support リポジトリで新しいイシューを投稿します。FLEDGE のイシューテンプレートを必ず選択してください。
- GitHub の demo code リポジトリでイシューを提起してください。
- API を使ってユースケースを実現する方法に関する一般的な質問については、提案のリポジトリでイシューを提出してください。
Chrome での FLEDGE API の実装に関するバグとイシューについては、以下の方法を利用できます。
- API について報告された既存のイシューを表示します。
- 新しいイシューは、crbug.com/new に報告してください。
アップデートを入手する
- API のステータス変更の通知を受け取るには、開発者向けメーリングリストに参加してください。
- API に関する現在進行中のすべてのディスカッションを細かくフォローするには、GitHub の提案ページにある Watch ボタンをクリックしてください。これには、GitHub アカウントを持っているか作成する必要があります。
- プライバシーサンドボックスの包括的な最新情報を入手するには、RSS フィードで「プライバシーサンドボックスの進行状況」を購読してください。
詳細について
- FLEDGE API : あまり技術的でない、提案の概要。
- FLEDGE デモ: FLEDGE の基本的なデプロイのウォークスルー。
- FLEDGE デモ動画: デモコードを説明し、FLEDGE のデバッグに Chrome DevTools を使用する方法を示します。
- FLEDGE API のテクニカル Explainer
- プライバシーサンドボックスの詳細
- Intent to Prototype。
写真提供: Ray Hennessy(Unsplash)