このページは Cloud Translation API によって翻訳されました。

FLEDGE API デベロッパーガイド

この記事の対象者

この投稿は、Protected Audience API の試験運用版として現在提供されている技術リファレンスです。

Protected Audience API は、この提案の技術的な概要ではありません。用語集も含まれています。
Protected Audience のデモでは、基本的な FLEDGE のデプロイについて解説しています。
Protected Audience のデモ動画では、デモコードの仕組みと、Chrome DevTools を使用して Protected Audience をデバッグする方法について説明しています。

Protected Audience とは

Protected Audience API は、リマーケティングやカスタムオーディエンスのユースケースに対応するためのプライバシーサンドボックスの提案です。第三者がサイトをまたいでユーザーの閲覧行動を追跡できないように設計されています。この API を使用すると、ブラウザによるデバイス上のオークションで、ユーザーが以前アクセスしたウェブサイトに関連する広告を選択できます。

Protected Audience は、TURTLEDOVE プロポーザルファミリーの中で Chromium に実装された最初のテストです。

以下の図に FLEDGE のライフサイクルの概要を示します。

FLEDGE ライフサイクルの各ステージの概要を示すイラスト — FLEDGE のライフサイクル

Protected Audience を試すにはどうすればよいですか？

Protected Audience のデモ

広告主とパブリッシャーのサイトでの基本的な Protected Audience のデプロイに関するチュートリアルは、protected-audience-demo.web.app で確認できます。

デモ動画では、デモコードの仕組みと、Chrome DevTools を使用して Protected Audience のデバッグを行う方法を説明します。

Protected Audience オリジントライアルに参加する

パソコン版 Chrome ベータ版 101.0.4951.26 以降では、Protected Audience API、Topics API、Attribution Reporting API のプライバシーサンドボックスの関連性と測定のオリジントライアルを利用できます。

参加するには、オリジントライアルトークンに登録してください。

トライアルへの登録が成功したら、有効なトライアルトークンを提供するページで Protected Audience JavaScript API を試すことができます。たとえば、ブラウザに1 つ以上のインタレストグループに参加するようリクエストし、広告オークションを実施して広告を選択して表示させることができます。

Protected Audience のデモは、Protected Audience をエンドツーエンドで導入する基本的な例です。

Protected Audience 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);

Protected Audience のコードを実行する iframe（インタレストグループのオーナーによる navigator.joinAdInterestGroup() の呼び出しなど）は、オリジンと一致するトークンを提供する必要があります。

推奨される最初の Protected Audience オリジントライアルの詳細では、最初のトライアルの目標の詳細と、サポートされている機能について説明しています。

この API をテストする

パソコンの Chrome ベータ版 101.0.4951.26 以降を使用して、1 人のユーザーの Protected Audience をテストできます。

chrome://settings/adPrivacy ですべての Ad Privacy API を有効にする
コマンドラインからフラグを設定する。

iframe またはフェンス付きフレームで広告をレンダリングする

広告は、設定されているフラグに応じて <iframe> または <fencedframe> でレンダリングできます。

<fencedframe> を使用して広告を表示するには:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

<iframe> を使用して広告を表示するには:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

一時デバッグの損失/落札の報告方法を有効にするには、BiddingAndScoringDebugReportingAPI フラグを含めます。

フラグを使用して Chromium を実行するでは、コマンドラインから Chrome やその他の Chromium ベースのブラウザを実行する際にフラグを設定する方法が説明されています。Protected Audience フラグの全一覧は、Chromium ソースコード検索で確認できます。

Chrome の最新バージョンでサポートされる機能

Protected Audience は、Protected Audience の提案の以下の機能をテストする最初のテストとして、Chromium の機能フラグの背後で利用可能になります。

インタレストグループ: 広告の入札とレンダリングを設定するための関連メタデータとともにブラウザに保存されます。
購入者（DSP または広告主）によるオンデバイス入札: 保存されているインタレストグループと販売者からのシグナルに基づきます。
販売者（SSP またはパブリッシャー）によるデバイス上の広告選択: オークションの入札と購入者のメタデータに基づきます。
Fenced Frames の一時的に緩和したバージョンでの広告レンダリング: 広告のレンダリングでネットワークアクセスとロギングが可能です。

機能のサポートと制約については、API の説明で詳しく説明しています。

インタレストグループの権限

Protected Audience の現在の実装では、ページ上の任意の場所（クロスドメイン iframe からのものも含む）から joinAdInterestGroup() を呼び出せるようになっています。将来的には、サイト所有者がクロスドメイン iframe の権限ポリシーを調整する時間を確保したら、説明のとおり、クロスドメイン iframe からの呼び出しを禁止する予定です。

Key-Value サービス

Protected Audience 広告オークションの一環として、ブラウザは単純な Key-Value ペアを返す Key-Value サービスにアクセスして、残りのキャンペーン予算などの情報を広告購入者に提供できます。Protected Audience プロポーザルでは、このサーバーは「イベントレベルのロギングを行わず、これらのリクエストに基づいてその他の副作用がない」ことが義務付けられています。

Protected Audience の Key-Value サービスのコードがプライバシーサンドボックスの GitHub リポジトリで利用可能になりました。このサービスは Chrome と Android のデベロッパーが使用できます。ステータスの最新情報については、お知らせのブログ投稿をご覧ください。Protected Audience Key-Value サービスについて詳しくは、API の説明と信頼モデルの説明をご覧ください。

初期テストでは、「Bring Your Own Server」モデルを使用します。長期的には、アドテックがリアルタイムデータを取得するために、高信頼実行環境で実行されるオープンソースの Protected Audience Key-Value サービスを使用する必要があります。

エコシステムのテストに十分な時間を確保するため、サードパーティ Cookie のサポートが終了するまで、オープンソースの Key-Value サービス（TEE）を使用する必要はありません。この移行を実施する前に、デベロッパーの皆様にテストと導入を開始していただくために、十分な通知を行います。

検出機能のサポート

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');

Protected Audience をオプトアウトするにはどうすればよいですか？

Protected Audience API へのアクセスは、サイト所有者として、または個々のユーザーとしてブロックできます。

サイトがアクセスを制御するにはどうすればよいですか？

Protected Audience では最終的に、Protected Audience 機能を使用できるように権限ポリシーをサイトに設定することが義務付けられます。これにより、任意の第三者がサイトの認識なしに API を使用できないようにできます。ただし、初回オリジントライアル中のテストを容易にするため、この要件はデフォルトで免除されています。テスト期間中に Protected Audience 機能を明示的に無効にするサイトは、関連する権限ポリシーを使用してアクセスをブロックできます。

個別に設定できる Protected Audience 権限ポリシーは、次の 2 つです。

join-ad-interest-group は、インタレストグループにブラウザを追加する機能を有効、無効にします
run-ad-auction は、デバイス上のオークションを実施する機能を有効または無効にします

HTTP レスポンスヘッダーで次の権限ポリシーを指定すると、Protected Audience API へのアクセスをファーストパーティのコンテキストで完全に無効にできます。

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

iframe 要素に次の allow 属性を追加すると、iframe での API の使用を無効にできます。

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

詳しくは、Proposed First Protected Audience オリジントライアルの Permissions-Policy セクションをご覧ください。

ユーザーオプトアウト

ユーザーは、次のいずれかのメカニズムを使用して、Protected Audience API やその他のプライバシーサンドボックス機能へのアクセスをブロックできます。

Chrome の設定で、プライバシーサンドボックスの試用版を無効にする: [設定] > [セキュリティとプライバシー] > [プライバシーサンドボックス]。この URL には chrome://settings/adPrivacy からもアクセスできます。
Chrome の設定で、サードパーティ Cookie を無効にする（設定] > [セキュリティとプライバシー]）。
chrome://settings/cookies の [Cookie と他のサイトデータ] を [サードパーティの Cookie をブロックする] または [すべての Cookie をブロック] に設定します。
シークレットモードを使用します。

Protected Audience の解説では、API の設計要素の詳細を紹介し、API がプライバシー目標をどのように満たそうとしているかを説明します。

Protected Audience ワークレットをデバッグする

Chrome Canary 98.0.4718.0 以降では、Chrome DevTools 内で Protected Audience ワークレットをデバッグできます。

まず、[Sources] パネルの [Event Listener Breakpoints] ペインで新しいカテゴリを介してブレークポイントを設定します。

Chrome Canary の DevTools のスクリーンショット。[Sources] パネルの [Event Listener Breakpoints] ペインがハイライト表示されている。
[広告オークションワークレット] で [ビッダー入札フェーズの開始] が選択されている。

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

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

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

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

Protected Audience のイベントを監視する

Chrome DevTools の [Application] パネルで、Protected Audience のインタレストグループとオークションイベントを確認できます。

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

Chrome Canary の DevTools の [Application] パネル。Protected Audience のインタレストグループへの参加イベントに関する情報が表示されています。

Protected Audience が有効になっているブラウザで Protected Audience のデモパブリッシャーサイトにアクセスすると、DevTools に bid イベントと win イベントに関する情報が表示されます。

Chrome Canary の DevTools の [Application] パネル。Protected Audience オークションの入札と落札イベントに関する情報が表示されています。

Protected Audience API の仕組み

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

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

ノートパソコンのブラウザでカスタム自転車メーカーのサイトにアクセスしている人のイラスト。

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

重要な用語: デマンドサイドプラットフォーム（DSP）は、広告の購入を自動化するアドテックサービスです。広告主は DSP を使用して、さまざまなパブリッシャーサイトで広告インプレッションを購入します。パブリッシャーは、アドエクスチェンジと呼ばれるマーケットプレイスを通じて広告枠を販売し、DSP は広告主が購入するのに最適な広告インプレッションをプログラマティックに決定します。サプライサイドプラットフォーム（SSP）は、広告枠の販売を自動化するアドテックサービスです。SSP を使用すると、パブリッシャーは複数のアドエクスチェンジ、DSP、ネットワークに広告枠（広告が表示される空の長方形）を提供できます。これにより、幅広い見込み顧客が広告スペースに入札できます。

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

ノートパソコンのブラウザでサイトを閲覧している人のイラスト。ブラウザで JavaScript コードの JoinAdInterestGroup() が実行されている。

解説セクション: ブラウザがインタレストグループを記録

広告主のデマンドサイドプラットフォーム（DSP）（または広告主自体）が navigator.joinAdInterestGroup() を呼び出し、ブラウザが属しているグループのリストにインタレストグループを追加するようブラウザに指示します。この例では、グループの名前は custom-bikes、オーナーは dsp.example です。インタレストグループのオーナー（この場合は DSP）は、ステップ 4 で説明されている広告オークションの購入者になります。インタレストグループのメンバーシップは、ブラウザとユーザーのデバイスに保存され、ブラウザベンダーやその他の第三者と共有されることはありません。

注: joinAdInterestGroup() の呼び出しコンテキストのオリジンは、インタレストグループオーナーのオリジンと一致する必要があります。そのため、インタレストグループオーナーのオリジンが現在のドキュメント（独自のインタレストグループを持つウェブサイトなど）と一致している場合を除き、joinAdInterestGroup() は iframe から（DSP などから）呼び出す必要があります。runAdAuction でも同じ要件はないため、<script> タグから runAdAuction() を呼び出す方がクロスオリジン iframe よりもはるかにパフォーマンスが高いと考えられます。

joinAdInterestGroup() に次の権限を許可する必要があります。

訪問先のサイト
インタレストグループのオーナー

たとえば、malicious.example が dsp.example の許可なしに dsp.example をオーナーとして joinAdInterestGroup() を呼び出すことはできません。

アクセス先のサイトの権限

同一オリジン: デフォルトでは、アクセスされているサイトと同じオリジン（つまり現在のページの最上位フレームと同じオリジン）からの joinAdInterestGroup() 呼び出しに対して、権限が暗黙的に付与されます。サイトは Protected Audience の権限ポリシーヘッダーの join-ad-interest-group ディレクティブを使用して、joinAdInterestGroup() の呼び出しを無効にできます。

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

注: Protected Audience の現在の実装では、ページ上の任意の場所（クロスオリジンの iframe からのものも含む）からの joinAdInterestGroup() の呼び出しがデフォルトで許可されます。将来的には、サイト所有者が権限ポリシーを調整する時間を確保したら、Protected Audience の解説で説明されているように、クロスオリジンの 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 を超えないようにする必要があります。50 KiB を超えると、呼び出しが失敗します。2 つ目のパラメータには、インタレストグループの期間（上限 30 日）を指定します。連続する呼び出しにより、以前に保存された値が上書きされます。

重要なポイント: Protected Audience API メソッドのパラメータとして使用される URL はすべて、安全なオリジンからのものである必要があります。すべてのリソースは HTTPS URL で配信する必要があります。Protected Audience をローカルで実行している場合にこれを行う方法については、ローカル開発に HTTPS を使用する方法をご覧ください。また、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 プロパティは省略可能ですが、オークションに参加するために必要です。これらのプロパティを指定せずにインタレストグループを作成する場合は、たとえば、まだ実施していないキャンペーンやその他の今後の用途のために、インタレストグループのオーナーがインタレストグループにブラウザを追加する場合や、一時的に広告予算を使い切る場合があります。

** biddingLogicUrl、biddingWasmHelperUrl、dailyUpdateUrl、trustedBiddingSignalsUrl の URL は、所有者と同じ生成元である必要があります。ads URL と 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 日）が経過するまで何も行われません。同じインタレストグループ owner と name に対して navigator.joinAdInterestGroup() が再度呼び出されると、レート制限はリセットされます。

自動更新

オークションで読み込まれたすべてのインタレストグループは、オークションが完了すると自動的に更新されます。更新には手動の更新と同じレート制限が適用されます。オークションに参加している 1 つ以上のインタレストグループを持つ各オーナーは、オリジンとオーナーが一致する iframe から navigator.updateAdInterestGroups() が呼び出された場合と同様となります。

インタレストグループの広告を指定する

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

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

購入者はどのように入札しますか？

インタレストグループのオーナーが提供した biddingLogicUrl のスクリプトには、generateBid() 関数を含める必要があります。広告スペースの販売者が navigator.runAdAuction() を呼び出すと、インタレストグループのオーナーが入札に招待されると、ブラウザがメンバーとなっているインタレストグループごとに generatedBid() 関数が 1 回呼び出されます。つまり、generateBid() は候補広告ごとに 1 回呼び出されます。販売者は、navigator.runAdAuction() に渡されるオークション構成パラメータで decisionLogicUrl プロパティを提供します。この URL のコードには、オークションの各ビッダーに対して実行される scoreAd() 関数を含めて、generateBid() から返された入札をスコアリングする必要があります。

注: biddingWasmHelperUrl プロパティは省略可能ですが、ビッダーは、JavaScript ではなく WebAssembly で計算コストの高いサブルーチンを提供し、biddingLogicUrl が提供する JavaScript 関数から実行できます。指定する場合は、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: ... /* 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
広告に関する任意のメタデータ（販売者がこの入札や広告クリエイティブについて把握することを想定している情報など）。販売者](/privacy-sandbox/resources/glossary#ssp) は、オークションと意思決定の広告クリエイティブでこの情報を使用します。販売者は、オークションと決定のロジックでこの情報を使用します。
bid
オークションに参加する数値による入札単価。販売者は、さまざまな購入者の入札単価を比較できる立場にある必要があるため、入札単価は販売者が選択した単位（例: 1, 000 米ドル単位）で行う必要があります。入札単価がゼロまたは負の場合、このインタレストグループは販売者のオークションに一切参加しません。このメカニズムにより、購入者は、広告を表示する場所とできない場所に関するあらゆる広告主のルールを実装できます。
render
この入札がオークションで勝った場合にクリエイティブのレンダリングに使用される URL または URL のリストです。（API の解説で Ads Composed of Multiple Pieces をご覧ください）。この値は、インタレストグループに対して定義された広告の renderUrl と一致する必要があります。
adComponents
複数の要素で構成される広告のコンポーネント（最大 20 個）のリスト。navigator.joinAdInterestGroup() に渡されるインタレストグループ引数の adComponents プロパティから取得されます。

ブラウザにインタレストグループから退会するよう求める

インタレストグループのオーナーは、インタレストグループからブラウザを削除するようリクエストできます。つまり、ブラウザは、属しているグループのリストからインタレストグループを削除するように求められます。

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

ユーザーがサイトに戻り、ブラウザにインタレストグループを追加するよう求められた場合、インタレストグループのオーナーは、navigator.leaveAdInterestGroup() 関数を呼び出して、ブラウザにインタレストグループを削除するようリクエストできます。広告のコードでも、インタレストグループに対してこの関数を呼び出すことができます。

3. ユーザーが広告スペースを販売するサイトにアクセスする

ノートパソコンのブラウザでニュースサイトにアクセスする人物のイラスト。サイトの広告スロットは空になっている。

その後、このユーザーは広告スペースを販売するサイト（この例ではニュースウェブサイト）にアクセスします。サイトには広告枠があり、リアルタイムビッダーを使用してプログラマティックに販売しています。

4. 広告オークションがブラウザで行われる

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

解説セクション: 販売者がオンデバイスオークションを実施する

広告オークションは、多くの場合、パブリッシャーの SSP またはパブリッシャー自体によって行われます。オークションの目的は、現在のページで使用可能な 1 つの広告スロットに最も適した広告を選択することです。オークションでは、ブラウザが属しているインタレストグループに加え、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 を返します。これはレンダリングのためにフェンス付きフレームに渡されたときにブラウザでのみデコードできます。パブリッシャーのページでは落札広告を検査できません。

注: 前述のとおり、joinAdInterestGroup() の呼び出しコンテキストのオリジンは、インタレストグループオーナーのオリジンと一致している必要があります。そのため、インタレストグループオーナーのオリジンが現在のドキュメント（独自のインタレストグループを持つウェブサイトなど）と一致しない限り、joinAdInterestGroup() は iframe（DSP など）から呼び出す必要があります。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': {...}, 'https://another-buyer.example': {...}, ...}`	購入者ごとの、ページに関するコンテキストシグナル。
`perBuyerTimeouts`	任意	`50`	特定の購入者の `generateBid()` スクリプトの最大実行時間（ミリ秒）。
`componentAuctions`	任意	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	コンポーネントオークションの追加設定。

* 販売者は interestGroupBuyers: '*' を指定して、すべてのインタレストグループに入札を許可する。広告は、インタレストグループの所有者が含まれているかどうか以外の条件に基づいて承認または拒否されます。たとえば、広告クリエイティブがポリシーに準拠しているかどうか審査される場合があります。

** additionalBids は、Protected Audience の現在の実装ではサポートされていません。詳しくは、Protected Audience の説明のオークション参加者のセクションをご覧ください。

広告はどのように選択されますか？

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

ノートパソコンのブラウザでニュースのウェブサイトを閲覧している人物のイラスト。Protected Audience API を使用する広告オークションが実施され、参加者が Key-Value サービスからデータを取得しています。

解説セクション: Protected Audience の 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 オブジェクトです。

重要なポイント: Protected Audience をテストする現在の初期テストフェーズでは、trustedBiddingSignalsUrl のオリジンはインタレストグループのオーナーと同じである必要があります。詳しくは、インタレストグループのプロパティとお客様所有サーバーの持ち込み（Bring Your Own Server）をご覧ください。

6. 落札した広告が表示される

ノートパソコンのブラウザでニュースのウェブサイトを閲覧している人物のイラスト。自転車（20% オフ）の広告が表示され、フェンスで囲まれたフレーム内に広告が表示されていることを示す鍵が上に乗っている。

解説セクション: ブラウザが落札広告をレンダリングする

前述のとおり、runAdAuction() によって返される Promise は URN に解決され、レンダリングのためにフェンス付きフレームに渡され、サイトに落札広告が表示されます。

7. オークション結果がレポートされる

解説セクション: イベントレベルのレポート（現時点では）

注: 長期的な計画では、ブラウザで集計レポート API を使用して販売者と購入者のオークション結果をレポートできるようにする予定です。一時的なイベントレベルのレポートメカニズムとして、販売者に reportResult() を実装し、落札者の reportWin() を実装するコードで sendReportTo() 関数を呼び出すことができます。この引数は 1 つの引数を取ります。この文字列はオークションの完了後に取得される URL を表す文字列で、報告するイベントレベルの情報がエンコードされています。

営業担当者が結果を報告

説明セクション: レンダリングに関する販売者レポート

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 引数として使用されます。

落札したビッダーレポートの結果

解説セクション: 購入者によるレンダリングと広告イベントに関するレポート

落札者の JavaScript（generateBid() も提供されます）に reportWin() 関数を含めて、オークション結果をレポートできます。

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

注: Chrome の現在の Protected Audience 実装では、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 という単一の引数を取ります。これらは、異なる URL 引数を使用して、scoreAd() と generateBid() の両方で複数回呼び出すことができます。

Chrome では、オークションが完了した場合にのみ、デバッグの損失/落札レポートが送信されます。オークションがキャンセルされた場合（新しいナビゲーションなど）、レポートは生成されません。

Chrome では、これらの方法がデフォルトで利用可能です。メソッドをテストできるようにするには、chrome://settings/adPrivacy で広告プライバシー API をすべて有効にします。コマンドラインフラグを使用して Chrome を実行し、Protected Audience を有効にする場合は、BiddingAndScoringDebugReportingAPI フラグを指定してメソッドを明示的に有効にする必要があります。フラグが有効になっていない場合、メソッドは引き続き使用できますが、何も行われません。

8. 広告のクリックが報告される

ニュースサイトで、フェンスで囲まれた枠内の自転車の広告をクリックしているイラスト。販売者と購入者に送られるレポートデータが示されています。

フェンス付きフレーム内に表示された広告のクリックが報告されます。この仕組みについて詳しくは、フェンス付きフレーム広告のレポートをご覧ください。

次の図は、Protected Audience の広告オークションの各ステージの概要を示しています。

Protected Audience 広告オークションの各段階の概要を示すイラスト

Protected Audience と TURTLEDOVE の違いは何ですか？

Protected Audience は、TURTLEDOVE ファミリーのプロポーザルの中で Chromium に実装された最初のテストです。

Protected Audience は、TURTLEDOVE の基本原則に準拠しています。オンライン広告には、以前広告主や広告ネットワークと接点を持ったことのある、興味 / 関心を持つ可能性がある人に広告を表示することを基本としているものがあります。これまで、広告主がウェブサイトをまたいで閲覧する特定の人物を認識することは、現代のウェブにおけるプライバシーの大きな懸念の一つでした。

TURTLEDOVE の取り組みは、このユースケースに対処するための新しい API を提供すると同時に、プライバシーに関する重要な進歩を提供することです。

ユーザーが興味を持っていると広告主が考える情報は、広告主ではなくブラウザが保持します。
広告主は興味 / 関心に基づいて広告を配信できますが、その興味 / 関心と、ユーザーに関するその他の情報（具体的には、ユーザーが誰で、どのページにアクセスしているか）を組み合わせることはできません。

Protected Audience は、この API を使用するデベロッパーにとってより良いサービスを提供するために、TURTLEDOVE と、関連する一連の変更の提案から発展しました。

SPARROW では、Criteo は高信頼実行環境（TEE）で実行される「Gatekeeper」サービスモデルの追加を提案しました。Protected Audience では、リアルタイムのデータ検索と集計レポートのための TEE の使用が限定的です。
NextRoll の TERN と Magnite の PARRROT の提案では、デバイス上のオークションにおける購入者と販売者のさまざまな役割について説明しています。Protected Audience の広告の入札/スコアリングのフローは、この作業に基づいています。
RTB House の結果ベースおよびプロダクトレベルの TURTLEDOVE の変更により、デバイス上のオークションの匿名性モデルとパーソナライズ機能が改善されました。
PARAKEET は、TURTLEDOVE のような広告サービスに対する Microsoft の提案です。ブラウザとアドテックプロバイダの間の TEE で実行されるプロキシサーバーを利用して、広告リクエストを匿名化し、プライバシープロパティを適用します。Protected Audience では、このプロキシモデルを採用していません。Google は、PARAKEET と Protected Audience の JavaScript API を連携させ、両方の提案の長所をさらに組み合わせる今後の取り組みをサポートします。

Protected Audience では、ユーザーに表示される広告をウェブサイトの広告ネットワークが学習することはまだ阻止されていません。この API は今後さらに非公開になるよう変更される予定です。

どのようなブラウザ構成を利用できますか？

ユーザーは、chrome://settings/adPrivacy で最上位の設定を有効または無効にすることで、Chrome のプライバシーサンドボックスのトライアルへの参加を調整できます。初期テストでは、このプライバシーサンドボックスの大まかな設定を使用して Protected Audience をオプトアウトできます。Chrome では、ユーザーがアクセスしたウェブサイトで自分が追加されたインタレストグループのリストを確認し、管理できるようにする予定です。プライバシーサンドボックステクノロジー自体と同様に、ユーザー設定は、ユーザーや規制当局などからのフィードバックによって進化する可能性があります。

Chrome で利用可能な設定は、Protected Audience の提案の進展に応じて、テストとフィードバックに基づいて継続的に更新されます。将来的には、Protected Audience と関連データを管理するために、より詳細な設定を提供する予定です。

API 呼び出し元は、ユーザーがシークレットモードでブラウジングしている場合、グループメンバーシップにアクセスできません。また、ユーザーがサイトデータを消去すると、メンバーシップが削除されます。

対応してフィードバックを共有する

GitHub: 提案の閲覧、質問の投稿、ディスカッションのフォローを行います。
W3C: ウェブ広告ビジネスの改善グループで業界のユースケースについて議論する。
デベロッパーサポート: プライバシーサンドボックスデベロッパーサポートリポジトリで、質問したりディスカッションに参加したりできます。
FLEDGE メーリングリスト: fledge-api-announce は、API に関するお知らせと更新を提供します。
Protected Audience のスケジュール設定された呼び出し（第 2 週ごと）に参加します。誰でも参加できます。参加するには、まず WICG に参加してください。積極的に参加することも、ただ視聴することもできます。
公開フォーラム以外の Chrome チームに非公開でフィードバックを共有するには、プライバシーサンドボックスのフィードバックフォームを使用してください。

サポートを受ける

実装、デモ、ドキュメントについて質問がある場合:

privacy-sandbox-dev-support リポジトリで新しい問題を報告する。Protected Audience の問題テンプレートを必ず選択してください。
GitHub のデモコードリポジトリで問題を報告します。
API を使用してユースケースを満たす方法に関する一般的な質問については、プロポーザルリポジトリで問題を報告してください。

Chrome での Protected Audience API の実装に関するバグや問題の場合: * API について報告された既存の問題を確認する。 * crbug.com/new で新しい問題を報告します。

補足説明

Protected Audience API: 技術的な概要ではないプロポーザルの概要。
Protected Audience のデモ: Protected Audience の基本的なデプロイについて説明します。
Protected Audience のデモ動画: デモコードについて説明し、Protected Audience のデバッグに Chrome DevTools を使用する方法を説明しています。
Protected Audience API 技術解説
プライバシーサンドボックスの詳細
プロトタイピングの意図

写真撮影: Ray Hennessy、Unsplash