Get Inspired
Docs
Blog
Articles

FLEDGE API 開発者ガイド

公開日 • 更新日

翻訳先言語： English

Sam Dutton
Sam Dutton

Developer Advocate, Google Chrome

Website Twitter GitHub Glitch Mastodon
Kevin K. Lee
Kevin K. Lee

Developer Relations Engineer, Google Chrome

Twitter GitHub

この記事の対象者

この記事は、実験的な FLEDGE API の現在のイテレーションに関する技術リファレンスです。

  • FLEDGE APIは、提案の技術的な概要ではなく、用語集もあります。

  • FLEDGE デモでは、FLEDGE の基本的なデプロイのウォークスルーを説明します。

  • FLEDGE デモ動画では、デモコードがどのように動作するかを説明し、FLEDGE のデバッグに Chrome DevTools を使用する方法を示します。

FLEDGEとは

FLEDGE は、リマーケティングおよびカスタム オーディエンスのユースケースに対応するためのプライバシーサンドボックスの提案であり、サードパーティがサイトを跨いでユーザーのブラウジング行動を追跡できないように設計されています。この API は、ブラウザによるオンデバイス オークションを有効にし、ユーザーが以前にアクセスしたウェブサイトに関連する広告を選択します。

FLEDGE は、TURTLEDOVE ファミリの提案の中で Chromium に実装された最初の実験です。

以下の図は、FLEDGE のライフサイクルの概要を示しています（拡大版を表示）。

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 オリジントライアルの詳細）には、最初のトライアルの目標に関する詳細と、どの機能がサポートされているかが説明されています。

Caution

有効なトライアルトークンを提供するページであっても、すべてのユーザーがプライバシーサンドボックスの広告関連のオリジントライアルの対象となるわけではありません。

プライバシーサンドボックス広告関連 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');
Caution

現在のページでの機能のサポートは、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 ワークレットをデバッグできます。

最初のステップは、[ソース] パネルの [イベント リスナー ブレークポイント] ペインの新しいカテゴリを介してブレークポイントを設定することです。

[ソース] パネルの [イベント リスナー ブレークポイント] ペインが強調表示されている、Chrome Canary の DevTools のスクリーンショット。[広告オークション ワークレット] で [ビッダーの入札フェーズの開始] が選択されています。

ブレークポイントがトリガーされると、ワークレット スクリプトの最上位にある最初のステートメントの前で実行が一時停止されます。通常のブレークポイントまたはステップ コマンドを使用して、入札/スコアリング/レポート機能自体にアクセスできます。

ライブ ワークレット スクリプトも [スレッド] パネルの下に表示されます。

Chrome Canary の DevTools のスクリーンショット。[ソース] パネルの [スレッド] ペインが強調表示され、一時停止されている現在のワークレット スクリプトが表示されています。

一部のワークレットは並行して実行される可能性があるため、複数のスレッドがそこで「一時停止」状態になる可能性があります。スレッド リストを使用してスレッドを切り替え、必要に応じてスレッドを再開または詳細に調べることができます。

FLEDGE イベントを観察する

Chrome DevTools の [アプリケーション] パネルから、FLEDGE インタレスト グループとオークション イベントを観察できます。

FLEDGE が有効になっているブラウザで FLEDGE のデモショッピングサイトにアクセスすると、DevTools に join イベントに関する情報が表示されます。

Chrome Canary の DevTools [アプリケーション] パネル。FLEDGE インタレストグループ参加イベントに関する情報が表示されています。

これで、FLEDGE が有効になっているブラウザでFLEDGE のデモサイト運営者サイトにアクセスすると、DevTools は bid イベントと win イベントに関する情報を表示します。

Chrome Canary の DevTools [アプリケーション] パネル。FLEDGE オークションの入札および落札イベントに関する情報が表示されます。

サイトに移動したときに DevTools が開いていなかった場合は、ページを更新して FLEDGE イベントを表示する必要があります。

FLEDGE API の仕組み

この例では、ユーザーがカスタム バイク メーカーのウェブサイトを閲覧した後、ニュースサイトにアクセスすると、そのバイク メーカーの新しい自転車の広告が表示されます。

Warning

この記事で説明されているすべての機能が、現在 Chrome でテストされている FLEDGE API のバージョンに実装されている（または完全に実装されている）わけではありません。機能フラグを使用したテストでは、 機能フラグを使用してコマンドラインから実行される Chrome で現在どの FLEDGE 機能をテストできるかについて説明されています。

FLEDGE の機能は、実装作業が続くにつれて徐々に追加されることを期待しています。API がオリジントライアルの段階に達すると、定期更新のリストで実装済みの部分とまだ進行中の部分をお知らせします。

1. ユーザーが広告主のサイトにアクセスする

ノートパソコンのブラウザでカスタム バイク メーカーのサイトにアクセスしている人を示す図。

ユーザーがカスタム バイク メーカー（この例では広告主）のウェブサイトにアクセスし、手作りのスチール バイクの製品ページにしばらくアクセスしたとします。これにより、バイク メーカーはリマーケティングの機会を得ることができます。

Key Term

デマンドサイド プラットフォーム（DSP）は、広告購入の自動化に使用されるアドテック サービスです。 DSP は、広告主がさまざまなサイト運営者サイトで広告インプレッションを購入するために使用されます。サイト運営者は、アドエクスチェンジと呼ばれるマーケットプレイスを通じて広告枠を売りに出し、DSP は、広告主が購入するのに最も意味のある利用可能な広告インプレッションをプログラムで決定します。

サプライサイド プラットフォーム（SSP）は、広告枠の販売を自動化するために使用されるアドテック サービスです。SSP を使用すると、サイト運営者は広告枠（広告が表示される空の矩形）を複数のアドエクスチェンジ、DSP、およびネットワークにオファーできます。これにより、幅広い潜在的なバイヤーが広告スペースに入札できるようになります。

2. ユーザーのブラウザがインタレストグループを追加するよう求められる

ノートパソコンのブラウザでサイトを表示している人を示す図。JavaScript コード joinAdInterestGroup() がブラウザで実行されています。

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 のリストを使用して提供される他のドメインに委譲されることです。

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. ブラウザで広告オークションが実行される

ノートパソコンのブラウザでニュースサイトを表示している人を示す図。FLEDGE API を使用した広告オークションが行われています。

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 サービスからリアルタイム データを受け取る

ノートパソコンのブラウザでニュースサイトを表示している人を示す図。FLEDGE API を使用した広告オークションが行われており、参加者が 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. 落札した広告が表示される

ノートパソコンのブラウザでニュースサイトを表示している人を示す図。自転車（20% オフ）の広告が表示されています。上部のロックは、広告が Fenced Frame に表示されることを示します。

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 Frame にレンダリングされた広告のクリックが報告されます。これがどのように機能するかについて詳しくは、Fenced Frames 広告のレポートを参照してください。


以下の図は、FLEDGE の広告オークションの各段階の概要を示しています（拡大版を表示）。

FLEDGE 広告オークションの各段階の概要を示す図

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 呼び出し元はグループ メンバーシップにアクセスできません。また、ユーザーがサイトデータを消去すると、メンバーシップが削除されます。



エンゲージメントとフィードバックの共有

サポートを受ける

ユーザーの実装、デモ、またはドキュメントについて質問するには、以下の方法を利用できます。

Chrome での FLEDGE API の実装に関するバグとイシューについては、以下の方法を利用できます。

アップデートを入手する

詳細について

写真提供: Ray Hennessy（Unsplash）

更新日 • 記事を改善する

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.