Protected Audience API: 開発者ガイド

Protected Audience API を初めて使用する方は、API の概要を説明した Protected Audience API の概要をお読みください。

この記事は、実験的な Protected Audience API の最新のイテレーションに関するテクニカル リファレンスとして開発者向けに執筆されています。基本的な Protected Audience API の導入に関するデモと、広告の買い手と売り手向けの API リファレンスが提供されています。

# 実装状況

• Protected Audience API の提案は現在、大規模な導入に向けたリリースに近づいています。質問を投稿し、ディスカッションをお読みください。
• Protected Audience API の保留中の機能のステータスでは、Protected Audience API と機能の変更と機能強化について詳しく説明します。
• Blink のステータス。
• Protected Audience API Chrome プラットフォームのステータス: Chrome の Protected Audience API に特化したステータス。
• Ads API Chrome プラットフォームのステータス: 広告を促進するための API のコレクション: Protected Audience API、Topics、Fenced Frames、Attribution Reporting。

API のステータス変更の通知を受け取るには、開発者向けメーリングリストに参加してください。

# Protected Audience API とは？

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

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

# Protected Audience API を試す

# 利用可能な API リファレンス

このドキュメントは、Protected Audience API の概要です。特定の API メソッドとパラメーターを探している場合は、以下をご覧ください。

• joinAdInterestGroup() と generateBid() の買い手向けガイド
• Protected Audience API runAdAuction() の売り手向けガイド
• 買い手向けの reportWin() ガイドと売り手向けの reportResult() ガイド
• Protected Audience API のトラブルシューティング

また、Protected Audience API 広告オークションの待ち時間に関するベストプラクティスもご覧ください。

# Protected Audience API のデモ

広告主とサイト運営者のサイト間の基本的な Protected Audience API のデプロイに関するウォークスルーは、protected-audience-demo.web.app で入手できます。

# chrome://flags または機能フラグでテストする

デスクトップでは Chrome ベータ版 101.0.4951.26 以降を使って、1 人のユーザーに対して Protected Audience API をテストできます。

• chrome://flags/#privacy-sandbox-ads-apis を有効にします。
• コマンドラインでフラグを設定します。利用可能な Protected Audience API フラグの全リストは、Chromium Code Search で検索できます。

# iframe または Fenced Frame に広告を表示する

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

<fencedframe> を使用して広告をレンダリングするには:

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

<iframe> を使用して広告をレンダリングするには:

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

BiddingAndScoringDebugReportingAPI フラグを含めて、一時的なデバッグの落札/競り負けレポートメソッドを有効にします。

# サポートされる機能

Chromium でのフラグ設定による Protected Audience API は、Protected Audience API の以下の機能をテストするための最初の実験です。

• インタレスト グループ: 広告の入札とレンダリングを構成するための関連付けられたメタデータとともに、ブラウザによって保存されます。
• 買い手（DSP または広告主）によるオンデバイス入札: 保存されているインタレスト グループと売り手からのシグナルに基づきます。
• 売り手（SSP またはサイト運営者）によるオンデバイス広告の選択: 買い手からのオークション入札とメタデータに基づきます。
• 一時的に緩和されたバージョンの Fenced Frames での広告レンダリング: 広告のレンダリングが許可されたネットワーク アクセスとロギング。

機能のサポートと制約について詳しくは、Protected Audience API の Explainer をご覧ください。

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

Protected Audience API の現在の実装のデフォルトでは、クロスドメイン iframe も含むページ内のどこからでも joinAdInterestGroup() を呼び出すことができます。

将来的には、サイト所有者にクロスドメイン iframe の権限ポリシーを更新する時間ができたら、クロスドメイン iframe からの呼び出しを禁止する予定です。

# Key/Value サービス

Protected Audience API 広告オークションをサポートするために、ブラウザは Key/Value サービスにアクセスして、Protected Audience API 広告オークションをサポートするリアルタイム情報を取得できます。この情報は、さまざまな方法で使用できます。

• 買い手が、広告キャンペーンの残りの予算を計算する場合。
• 売り手が、広告クリエイティブをサイト運営者のポリシーに照らして確認する必要がある場合。

Protected Audience API Key/Value サービスコードが公開されました。ステータスの更新については、ブログの発表記事をご覧ください。

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

タイムラインの更新については、Protected Audience API サービスのブログ記事をご覧ください。この移行が行われる前に、開発者がテストと採用を開始できるように十分な通知を行います。

# 機能サポートを検出する

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

# Protected Audience API の仕組み

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

Protected Audience API の機能は、実装の作業が進むにつれて追加されます。

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

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

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

広告主のデマンドサイド プラットフォーム（DSP）（または広告主自体）は、navigator.joinAdInterestGroup() を呼び出して、ブラウザがメンバーであるグループのリストにインタレストグループを追加するようブラウザに要求します。

この例では、グループの名前は custom-bikes で、オーナーは dsp.example です。インタレスト グループのオーナー（この場合は DSP）は、Protected Audience API 広告オークションの買い手になります。インタレスト グループのメンバーシップは、ブラウザによってユーザーのデバイスに保存され、ブラウザベンダーや他の誰とも共有されません。

• Protected Audience API の Explainer を読む: ブラウザによるインタレスト グループの記録
• API ガイド を読む : 買い手と DSP 向け。joinAdInterestGroup() に参加して入札を生成する方法を学びます。

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

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

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

# 買い手の入札方法

generateBid() は、インタレストグループのオーナーが入札に招待された場合に、ブラウザがメンバーであるインタレスト グループごとに呼び出されます。

generatedBid() 開発者向けドキュメントをお読みください。

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

後になって、ユーザーは広告スペースを販売するサイト（この例ではニュースサイト）にアクセスします。このサイトには広告枠があり、リアルタイム入札を使用してプログラムで販売しています。

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

広告オークションは、サイト運営者のサプライサイド プロバイダー（SSP）またはサイト運営者自身によって実行される可能性があります。オークションの目的は、現在のページで使用可能な単一の広告スロットに最も適した広告を選択することです。オークションでは、広告スペースの買い手と Key/Value サービスの売り手からのデータとともに、ブラウザがメンバーであるインタレスト グループが考慮されます。

• Protected Audience API の Explainer を読む: 売り手によるオンデバイス オークションの実行
• API ガイドを読む: 売り手は、runAdAuction() と 広告オークションの待ち時間のベストプラクティスについて詳しく知ることができます。

# 5. 売り手と参加する買い手が、Key/Value サービスにリアルタイム データをリクエストする

広告オークション中、売り手は Key/Value サービスにリクエストを送信して、特定の広告クリエイティブに関するリアルタイム データを要求できます。売り手は、trustedScoringSignalsUrl プロパティと、オークション内のすべてのインタレスト グループの ads と adComponents フィールドにあるすべてのエントリの renderUrl から得るキーを使って、runAdAuction() を実行中にこの情報を要求できます。

買い手は、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 API の Explainer を読む: Protected Audience API Key/Value サービスからリアルタイム データを取得する。
• **Protected Audience API Key/Value サービスのオープンソース化**をお読みください。

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

runAdAuction() によって返される Promise は、オークション構成で resolveToConfig フラグが true に設定されている場合、Fenced Frame 構成オブジェクト（FencedFrameConfig）に解決されます。フレーム構成は、フレームを落札広告に移動する目的で Fenced Frame によって使用されますが、広告の URL はフレームのエンベッダーには表示されません。

Fenced Frame 構成オブジェクトは、M114 以降で利用可能です。FencedFrameConfig オブジェクトの詳細については、Chrome ブログの記事をご覧ください。

• Protected Audience API の Explainer を読む: ブラウザによる落札広告のレンダリング

# 7. オークション結果が報告される

長期的には、Private Aggregation API を使用して、ブラウザが売り手と買い手にオークション結果をレポートできるようにすることを計画しています。

一時的なイベントレベルのレポートの仕組みとして、売り手用に reportResult() を実装し、落札者用に reportWin() を実装するコードは、sendReportTo() 関数を呼び出すことができます。これはオークションの完了後に取得される URL を表す文字列を引数として取ります。これにより、レポートされるイベントレベルの情報が暗号化されます。

• API ガイドを読む: 売り手と買い手のレポートについてお読みください。

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

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

# 貢献とフィードバックの共有

# サポートを受ける

実装、デモ、またはドキュメントに関する質問とサポートについては、以下をご覧ください。

• GitHub: Explainer を読み、質問を投稿したり、ディスカッションを閲覧したりできます。
• デモ: demo code リポジトリでイシューを提起してください。
• 開発者サポート: Privacy Sandbox Developer Support リポジトリでは、質問したり、ディスカッションに参加したりできます。Protected Audience API のイシュー テンプレートを選択してください。
• Chrome の実装: Protected Audience API の Chrome の実装に関するバグやイシューについて、既存のイシューを閲覧したり、新しいイシューを提起したりできます。

Protected Audience API でのニーズへの対応に関する一般的な質問については、API のリポジトリでイシューを報告してください。また、W3C の Improving Web Advertising Business Group で業界のユースケースについて話し合うこともできます。

プライバシー サンドボックスのフィードバック フォームを使用すると、公開フォーラムの外で Chrome チームと非公開でフィードバックを共有できます。

# オプトアウト

Protected Audience API からのオプトアウトをご希望ですか？サイトオーナーまたは個人ユーザーとして Protected Audience API へのアクセスをブロックする方法をご覧ください。

# アップデートを入手する

• API ステータス変更の通知を受け取るには、開発者向けメーリングリストに参加してください。
• API に関する現在進行中のすべてのディスカッションを細かくフォローするには、GitHub の API ページにある Watch ボタンをクリックしてください。これには、GitHub アカウントを持っているか作成する必要があります。
• プライバシー サンドボックスの包括的な最新情報を入手するには、RSS フィードで「プライバシー サンド ボックスの進行状況」を購読してください。
• Protected Audience API の定例会議にご参加ください（隔週）。どなたでも参加できますが、参加するにはまず、WICG に参加してください。積極的に参加することも、聞くだけでも構いません。