このページは 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、Topics、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() 呼び出しなど）は、オリジンと一致するトークンを提供する必要があります。

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

`chrome://flags` または機能フラグを使用してテストする

パソコンで Chrome ベータ版 101.0.4951.26 以降を使用して、1 人のユーザーに対して Protected Audience をテストできます。 * chrome://flags/#privacy-sandbox-ads-apis を有効にします。 * コマンドラインからフラグを設定する。

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 提案の以下の機能をテストする最初のテストとして、Chromium の機能フラグの背後で Protected Audience を利用できるようになりました。

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

機能のサポートと制約については、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 の権限ポリシーは、個別に設定できます。 * join-ad-interest-group は、ブラウザをインタレストグループに追加する機能を有効または無効にします * run-ad-auction は、デバイス上のオークションを実施する機能を有効または無効にします。

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

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

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

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

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

ユーザーオプトアウト

ユーザーは次のいずれかの方法で、Protected Audience API とその他のプライバシーサンドボックス機能へのアクセスをブロックできます。

Chrome の [設定] > [セキュリティとプライバシー] > [プライバシーサンドボックス] で、プライバシーサンドボックスの試用版を無効にします。chrome://settings/adPrivacy からもアクセスできます。
Chrome の設定でサードパーティの Cookie を無効にする: [設定] > [セキュリティとプライバシー] に移動します。
[Cookie と他のサイトデータ] を chrome://settings/cookies からの [サードパーティの 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] ペインがハイライト表示されています。
[広告オークションワークレット] で [ビッダー入札フェーズの開始] が選択されている。

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

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

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

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

Protected Audience イベントをモニタリングする

Chrome DevTools の [Applications] パネルで、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() には次の許可が必要です。 * アクセス先のサイト * インタレストグループのオーナー

たとえば、dsp.example の権限なしに、malicious.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 以下にする必要があります。そうしないと、呼び出しは失敗します。2 番目のパラメータでは、インタレストグループの期間（上限 30 日）を指定します。連続して呼び出すと、以前に格納されていた値が上書きされます。

キーポイント: Protected Audience API メソッドのパラメータとして使用する URL はすべて、安全なオリジンからのものでなければなりません。すべてのリソースは HTTPS URL で配信する必要があります。ローカル開発で HTTPS を使用する方法では、Protected Audience をローカルで実行する場合の手順について説明しています。また、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 プロパティは省略可能ですが、ビッダーは、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: ... /* 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 の説明の複数の要素で構成される広告をご覧ください）。この値は、インタレストグループに対して定義された広告のいずれかの renderUrl と一致する必要があります。
adComponents
複数の要素で構成される広告のコンポーネントを最大 20 個含むオプションのリスト。navigator.joinAdInterestGroup() に渡されるインタレストグループ引数の adComponents プロパティから取得されます。

ブラウザにインタレストグループからの退会を依頼する

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

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

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

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

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

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

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

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

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

広告オークションは、多くの場合、パブリッシャーの 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 を返します。これをブラウザでデコードできるのは、レンダリング用のフェンス付きフレームに渡されたときのみです。パブリッシャーのページでは落札された広告を検査できません。

注: 前述のように、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 の生成元がインタレストグループのオーナーと同じである必要があります。インタレストグループのプロパティとお客様所有サーバーの使用をご覧ください。

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

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

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

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

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

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

注: 長期的な計画では、ブラウザから Aggregate Reporting 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()

これらのメソッドはそれぞれ 1 つの引数（オークションの完了後に取得する URL）を取ります。scoreAd() と generateBid() の両方で、異なる URL 引数を使用して複数回呼び出すことができます。

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

chrome://flags/#privacy-sandbox-ads-apis が有効になっている場合、これらのメソッドは Chrome でデフォルトで使用できます。ただし、コマンドラインフラグを使用して Chrome を実行し、Protected Audience を有効にする場合は、BiddingAndScoringDebugReportingAPI フラグを含めることでメソッドを明示的に有効にする必要があります。このフラグが有効になっていない場合、メソッドは引き続き使用できますが、何も行いません。

8. 広告のクリックがレポートされる

ニュースウェブサイトで、フェンスの枠内の自転車の広告をクリックしている人物と、販売者と購入者にレポートデータが渡されているイラスト。

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

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

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

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

Protected Audience は、TURTLEDOVE の提案ファミリーの中で Chromium に実装される最初のテストです。

Protected Audience は TURTLEDOVE の大まかな原則に従っています。オンライン広告の中には、過去にその広告主や広告ネットワークと接点を持ったことのある、関心を持つ可能性がある人物への広告表示を前提としたものもありました。これまで、広告主はウェブサイトを閲覧中に特定の人物を認識することができましたが、これは今日のウェブにおけるプライバシーの大きな懸念事項です。

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

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

Protected Audience は、TURTLEDOVE と、この API を使用するデベロッパーにとってより良いサービスを提供するために、関連する修正案のコレクションから生まれました。

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 では、ユーザーがアクセスしたウェブサイト全体で、自分が追加されたインタレストグループのリストを確認、管理できるようにする予定です。プライバシーサンドボックステクノロジー自体と同様に、ユーザー設定も、ユーザー、規制機関などからのフィードバックによって進化する場合があります。

Google は、Protected Audience の提案の進捗に伴い、テストとフィードバックに基づいて Chrome で利用可能な設定を継続的に更新します。将来的には、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 のデモ動画: デモコードについて説明し、Chrome DevTools を使用して Protected Audience のデバッグを行う方法を示します。
Protected Audience API の技術的な説明
プライバシーサンドボックスの詳細
プロトタイピングの目的

写真撮影: Ray Hennessy（出典: Unsplash）