このページは 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 プロポーザルファミリー。

以下の図に 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() など）の呼び出しでは、そのオリジンと一致するトークンを指定する必要があります。

提案された最初の 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 は、Chromium のフィーチャートグルで初めて使用できるようになります。テストでは、Protected Audience のプロポーザルで以下の機能をテストできます。

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

API の解説では機能のサポートと制約について学びました

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

Protected Audience の現在の実装では、デフォルトで joinAdInterestGroup() の呼び出しが許可されています。ページ内の任意の場所（クロスドメインの iFrame を含む）に直接接続できます将来的には、サイト所有者がクロスドメインの 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 機能を使用できるようにします。これにより、任意の第三者がサイトの URL なしで API を使用できないようにできます。知識です。ただし、初回オリジントライアル中のテストを容易にするために、この要件はデフォルトで免除されています。テスト期間中に Protected Audience の機能を明示的に無効にするサイトの場合は、関連する権限ポリシーに従ってアクセスをブロックします。

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

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

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

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

iframe で API の使用を無効にするには、次の allow 属性を iframe 要素:

<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 を無効にする: [設定] >セキュリティとプライバシー。
[Cookie と他のサイトデータ] を [サードパーティの Cookie をブロックする] のいずれかに設定します。または [すべての Cookie をブロック] を選択します。提供元: chrome://settings/cookies。
シークレットモードを使用します。

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

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

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

まず、[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 の要件は異なるため、runAdAuction() の呼び出しを <script>タグはおそらく、クロスオリジンの iframe よりもはるかに高いパフォーマンスを発揮します。

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

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

たとえば、malicious.example が呼び出せないようにする必要があります。「joinAdInterestGroup()」に dsp.example をオーナーとして権限が付与されています dsp.example。

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

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

クロスオリジン: 現在のオリジンとは異なるオリジンから joinAdInterestGroup() を呼び出しアクセスしようとしているサイトで、コンテンツの呼び出しを許可する権限ポリシーがクロスオリジンの iframe から joinAdInterestGroup()。

注: Protected Audience の現在の実装では、joinAdInterestGroup() への呼び出しがデフォルトで許可されます。ページ内のどこからでも（クロスオリジンの iframe からでも可能）将来的に、サイト所有者が権限ポリシーの調整が必要なため、プランでは、デフォルトでクロスオリジン iframe。詳しくは Protected Audience の説明をご覧ください。

インタレストグループのオーナーからの許可

インタレストグループのオーナー権限は、joinAdInterestGroup() を呼び出すことで暗黙的に付与されますインタレストグループの所有者と同じオリジンの iframe からコピーできない。たとえば、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 はすべて、安全なオリジンの 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 には、インタレストグループのプロパティを定義する JSON を返すウェブサーバーを指定します。 navigator.joinAdInterestGroup() に渡されたインタレストグループオブジェクトに対応する ID です。このは、グループのオーナーが属性を定期的に更新するためのメカニズムを提供します。クリックします現在の実装では、次の属性を変更できます。

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

JSON で指定されていないフィールドは上書きされず、JSON に指定されたフィールドのみが取得されます。 updated - navigator.joinAdInterestGroup() を呼び出すと、既存のインタレストグループがすべて上書きされます。

更新はベストエフォート型であり、次の条件下では失敗する可能性があります。

ネットワークリクエストのタイムアウト（現在は 30 秒）。
その他のネットワーク障害。
JSON 解析エラーです。

連続した更新に時間がかかりすぎている場合も、更新がキャンセルされることがあります。ただし、キャンセルされた（残りの）更新にレート制限は適用されません。更新のレート制限は、上限は 1 日に 1 つですネットワークエラーが原因で失敗した更新は、1 時間後に再試行されます。インターネットからの切断により失敗した更新は、再接続時に直ちに再試行されます。

手動アップデート

現在のフレームの起点が所有するインタレストグループの更新は、 navigator.updateAdInterestGroups()。レート制限によって、更新が頻繁に行われなくなります。 navigator.updateAdInterestGroups() を繰り返し呼び出しても、レート制限まで何も実行されない期間（現在は 1 日）が経過しました。次の場合、レート制限はリセットされます。同じインタレストグループ owner と name に対して、navigator.joinAdInterestGroup() が再度呼び出されます。

自動更新

オークションで読み込まれたすべてのインタレストグループは、オークションが完了すると自動的に更新されます。手動更新と同じレート制限が適用されます。1 つ以上のインタレストグループを持つオーナーごとにオークションに参加すると、navigator.updateAdInterestGroups() が iframe の送信元が所有者と一致します。

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

ads オブジェクトと adComponents オブジェクトには、広告クリエイティブの URL が含まれます。任意で指定できます。入札時に使用できるメタデータです例:

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

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

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

注: biddingWasmHelperUrl プロパティは省略可能ですが、ビッダーから以下の情報が入力されます。 WebAssembly における計算コストの高いサブルーチン、 JavaScript ではなく、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
オークションに参加する入札単価の数値。営業担当者は比較できる立場に立つ必要がある複数の購入者が入札するため、入札は販売者が選択した単位で行う必要があります（例: 「USD/ 。入札単価がゼロまたはマイナスの場合、このインタレストグループはオークションに入札することはできませんこの仕組みにより、購入者はあらゆる広告主のルールを広告が表示されるかどうかが決まります。
render
この入札がオークションで勝った場合にクリエイティブを表示するために使用される URL または URL のリストです。（Ads Composed of Multiple Pieces をご覧ください）。をご覧ください）。値はいずれかの値の renderUrl と一致する必要があります。インタレストグループに対して定義された広告。
adComponents
最大 20 個のコンポーネントを指定できるオプションリスト複数の要素で構成される広告インタレストグループ引数の adComponents プロパティから取得されます navigator.joinAdInterestGroup() に渡されます。

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

インタレストグループのオーナーは、インタレストグループからブラウザを削除するようリクエストできます。その他のキーワードが含まれていると、ブラウザは、属しているインタレストグループのリストからインタレストグループを削除するよう求められます。

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

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

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

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

その後、このユーザーは広告スペースを販売するサイト（この例ではニュースウェブサイト）にアクセスします。このサイトには広告枠は、リアルタイムビッダー。

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

ノートパソコンのブラウザでニュースのウェブサイトを閲覧している人物のイラスト。広告
行われます。

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

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

注: 前述のとおり、Google Cloud Storage の joinAdInterestGroup() は、インタレストグループのオーナーのものと一致する必要がありますそのため、joinAdInterestGroup() は iframe から呼び出す必要があります（たとえば、（DSP から配信）されますが、インタレストグループの所有者が現在の（独自のインタレストグループを持つウェブサイトなど）。 runAdAuction の要件は異なるため、runAdAuction() の呼び出しを <script>タグはおそらく、クロスオリジンの 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 サービスからリアルタイムデータを取得する

広告オークションの期間中、広告スペースの販売者は次の方法で、特定の広告クリエイティブに関するリアルタイムデータを取得できます。次の trustedScoringSignalsUrl プロパティを使用して、Key-Value サービスにリクエストを送信する navigator.runAdAuction() にキーとともにオークション設定引数が渡されるすべての属性の ads と adComponents フィールドのすべてのエントリの renderUrl プロパティから追加することもできます

同様に、広告スペースの購入者は、インタレストグループ引数の trustedBiddingSignalsUrl プロパティと trustedBiddingSignalsKeys プロパティ navigator.joinAdInterestGroup() に渡されます。

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() 関数を呼び出すことができます。これには単一の引数: オークションの完了後に取得される 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>
}

この関数の戻り値は、落札したビッダーの sellerSignals 引数として使用されます。 reportWin() 関数を使用します。

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

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

落札者の 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 という単一の引数を取ります。ユーザーは、 scoreAd() と generateBid() の両方で、異なる URL 引数を指定して複数回呼び出す。

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 は TEE で実行されているプロキシサーバーに依存する TURTLEDOVE のような広告サービスに関する Microsoft の提案ブラウザとアドテックプロバイダの間のやり取り。広告リクエストを匿名化してプライバシー保護を強化するため。プロパティです。Protected Audience では、このプロキシモデルを採用していません。Google は JavaScript API を PARAKEET と Protected Audience との連携を強化し、最良の機能も備えています

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

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

ユーザーは、Chrome のプライバシーサンドボックスのトライアルへの参加を有効または無効にできます。 chrome://settings/adPrivacy の最上位設定。初期テストではプライバシーサンドボックスの高度な設定を使用して Protected Audience をオプトアウトできます。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 の実装に関するバグや問題の場合: * 既存の問題を表示する報告されます。 * crbug.com/new で新しい問題を報告します。

補足説明

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

写真撮影: Ray Hennessy、Unsplash