Private Aggregation API の概要

Protected Audience のデータと共有ストレージのクロスサイト データを使用して、集計データレポートを生成します。

キーポイント: プライバシー サンドボックスの関連性と測定のオリジン トライアルは 2023 年 9 月 20 日をもって終了し、Chrome ユーザーの 99% が API を利用できるようになりました。オリジン トライアルの登録は終了しました。各 API が有効になっているユーザーの割合を把握するには、Chrome のステータス グラフをご覧ください。

ウェブに必要な重要な機能を提供するため、Private Aggregation API は、プライバシーを保護しながらクロスサイト データの集計とレポートを行うように構築されています。

実装ステータス

提案	ステータス
共有ストレージのレポート確認で無効な Private Aggregation API レポートを防止 説明	Chrome で利用可能
Private Aggregation デバッグモードの提供状況は 3PC の利用資格に依存する GitHub の問題	Chrome M119 で利用可能
レポートの遅延を短縮する 説明	Chrome M119 で利用可能
Private Aggregation API と Google Cloud の集計サービスのサポート 説明	Chrome M121 で利用可能
集計可能レポートのペイロードのパディング 説明	Chrome M119 で利用可能
challengeReportBuyers レポートで非公開集計デバッグモードが利用可能に 説明	Chrome M123 でリリース予定
フィルタリング ID のサポート 説明	Chrome での初回リリースは 2024 年第 2 四半期を予定しています。

Private Aggregation API とは

Private Aggregation API を使用すると、デベロッパーは Protected Audience API のデータとShared Storage のクロスサイト データを含む集計データレポートを生成できます。

この API では現在、sendHistogramReport() という 1 つのオペレーションが用意されていますが、今後サポートされる予定です。ヒストグラム オペレーションを使用すると、定義した各バケット（API では集計キーと呼ばれます）内のユーザーのデータを集計できます。ヒストグラム呼び出しで値が蓄積され、ノイズが加えられた集計結果が概要レポートの形式で返されます。たとえば、各ユーザーがコンテンツを閲覧したサイトや、サードパーティのスクリプトのバグに遭遇したサイトの数が表示されます。この操作は、別の API のワークレット内で実行されます。

重要な用語: ワークレットを使用すると、特定の JavaScript 関数を実行し、リクエスト元に情報を返すことができます。ワークレット内では JavaScript を実行できますが、外部ページに対する操作や通信はできません。

たとえば、以前に共有ストレージにユーザー属性と地理データを記録していた場合は、Private Aggregation API を使用してヒストグラムを作成し、ニューヨーク市でコンテンツをクロスサイトで見たおおよそのユーザー数を把握できます。この測定値を集計するには、地域ディメンションを集計キーにエンコードし、集計可能な値でユーザー数をカウントします。

主な概念

集計キーと集計値を使用して Private Aggregation API を呼び出すと、ブラウザは集計可能レポートを生成します。

集計可能レポートは、収集とバッチ処理のためにサーバーに送信されます。バッチ処理されたレポートは、後で集計サービスによって処理され、概要レポートが生成されます。

Private Aggregation API に関する主なコンセプトの詳細については、Private Aggregation API の基礎のドキュメントをご覧ください。

Attribution Reporting との違い

Private Aggregation API には、Attribution Reporting API と多くの類似点があります。Attribution Reporting はコンバージョンを測定するために設計されたスタンドアロン API であるのに対し、Private Aggregation は Protected Audience API や Shared Storage などの API と組み合わせてクロスサイト測定用に構築されています。どちらの API も、概要レポートを生成するために集計サービスのバックエンドで使用される集計可能レポートを生成します。

Attribution Reporting は、異なるタイミングで発生するインプレッション イベントとコンバージョン イベントから収集されたデータを関連付けます。プライベート アグリゲーションは、単一のクロスサイト イベントを測定します。

この API をテストする

Private Aggregation API はローカルでテストできます。これを行うには、chrome://flags/#privacy-sandbox-ads-apis でプライバシー サンドボックス広告 API のテストフラグを有効にします。

プライバシー サンドボックス広告 API のテストを有効にして、これらの API を使用する

テストについて詳しくは、テストと参加をご覧ください。

デモを使用する

共有ストレージ用の Private Aggregation API のデモは goo.gle/shared-storage-demo で、コードは GitHub で入手できます。このデモでは、クライアントサイドの操作を実装し、サーバーに送信される集計可能レポートを生成します。

Protected Audience API 向け Private Aggregation API のデモは今後公開される予定です。

ユースケース

Private Aggregation はクロスサイト測定用の汎用 API で、Shared Storage ワークレットと Protected Audience API ワークレットで使用できます。最初のステップは、収集する情報を具体的に決定することです。これらのデータポイントが集計キーの基礎となります。

共有ストレージ付き

Shared Storage を使用すると、安全な環境でクロスサイト データの読み取りと書き込みを行って漏洩を防止できます。また、Private Aggregation API を使用すると、共有ストレージに保存されているクロスサイト データを測定できます。

ユニークリーチ測定

コンテンツを見たユニーク ユーザーの数を測定したい場合があります。Private Aggregation API は、「約 317 人のユニーク ユーザーが Content ID 861 を見た」といった回答を返すことができます。

ユーザーがすでにコンテンツを見たかどうかを示すフラグを共有ストレージに設定できます。フラグが存在しない最初のアクセスで、Private Aggregation が呼び出され、フラグが設定されます。クロスサイト アクセスを含め、ユーザーによる以降のアクセスでは、共有ストレージをチェックし、フラグが設定されている場合はプライベート アグリゲーションへのレポートの送信をスキップできます。

ユーザー属性の測定

さまざまなサイトでコンテンツを見たユーザーのユーザー属性を測定できます。

プライベート アグリゲーションでは、「ドイツ出身の 18 ～ 45 歳のユニーク ユーザーは約 317 人」といった回答が得られます。共有ストレージを使用して、サードパーティのコンテキストからユーザー属性データにアクセスします。後ほど、集計キーに年齢層と国のディメンションをエンコードすることで、非公開の集計を含むレポートを生成できます。

K+ 周波数測定

事前に選択した値 K で、特定のブラウザでコンテンツまたは広告を K 回以上表示したユーザーの数を測定したい場合があります。

非公開アグリゲーションでは、「約 89 人のユーザーが Content ID 581 を 3 回以上表示しています」といった回答が得られます。カウンタは共有ストレージ内で異なるサイトからインクリメントでき、ワークレット内で読み取ることができます。カウントが K に達したら、Private Aggregation を介してレポートを送信できます。

Protected Audience API を使用する場合

Protected Audience API は、リターゲティングとカスタム オーディエンスのユースケースを可能にします。また、Private Aggregation を使用すると、購入者と販売者のワークレットからイベントを報告できます。この API は、オークション入札の分布状況の測定などのタスクに使用できます。

Protected Audience API ワークレットから、sendHistogramReport() を使用してデータを直接集計し、reportContributionForEvent() を使用してトリガーに基づいてデータをレポートできます。これは Protected Audience API の特別な拡張機能です。

使用可能な関数

共有ストレージと Protected Audience API ワークレットで利用可能な privateAggregation オブジェクトでは、以下の関数を使用できます。

contributeToHistogram()

privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) を呼び出すことができます。ここで、集計キーは bucket、集計可能値は value です。bucket パラメータには BigInt が必要です。value パラメータには整数値が必要です。

リーチ測定のために共有ストレージで呼び出す方法の例を次に示します。

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

上記のサンプルコードでは、クロスサイト iframe コンテンツが読み込まれるたびにプライベート集計が呼び出されます。iframe コードがワークレットを読み込み、ワークレットは集計キー（バケット）に変換されたコンテンツ ID を使用して Private Aggregation API を呼び出します。

contributeToHistogramOnEvent()

Protected Audience API ワークレット内でのみ、特定のイベントが発生した場合にのみレポートを送信するトリガーベースのメカニズムを提供しています。また、この関数により、オークションの時点ではまだ利用できないシグナルをバケットと値に委ねることができます。

privateAggregation.reportContributionForEvent(eventType, contribution) メソッドは、トリガーとなるイベントを指定する eventType と、イベントがトリガーされたときに送信される contribution を受け取ります。トリガー イベントは、オークション終了後のオークション自体（オークションの落札イベントや損失イベントなど）から発生する場合もあれば、広告をレンダリングしたフェンスで囲まれたフレームで発生する場合もあります。 オークション イベントのレポートを送信するには、reserved.win、reserved.loss、reserved.always の 2 つの予約済みキーワードを使用します。フェンス付きフレームのイベントによってトリガーされたレポートを送信するには、カスタム イベントタイプを定義します。フェンス付きフレームからイベントをトリガーするには、Fenced Frames Ads Reporting API から入手できる fence.reportEvent() メソッドを使用します。

次の例では、オークションで落札イベントがトリガーされたときにインプレッション レポートを送信し、広告を表示したフェンス付きフレームから click イベントがトリガーされたときにクリック レポートを送信します。クリック率の計算には、この 2 つの値を使用できます。

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

詳しくは、拡張プライベート アグリゲーション レポートの説明をご覧ください。

enableDebugMode()

サードパーティ Cookie は引き続き使用できますが、デバッグモードを有効にすることでデバッグとテストを容易にする一時的なメカニズムを提供する予定です。デバッグ レポートは、Cookie ベースの測定値とプライベート アグリゲーションの測定値を比較するのに便利です。また、API の統合を簡単に検証することもできます。

ワークレットで privateAggregation.enableDebugMode() を呼び出すと、デバッグモードが有効になり、集計可能レポートに暗号化されていない（クリアテキスト）ペイロードが含まれます。その後、集計サービスのローカルテストツールを使用して、これらのペイロードを処理できます。

デバッグモードを使用できるのは、サードパーティ Cookie へのアクセスを許可されている呼び出し元のみです。呼び出し元がサードパーティ Cookie にアクセスできない場合、enableDebugMode() は通知なく失敗します。つまり、サードパーティ Cookie のサポートが終了すると、デバッグモードも使用できなくなります。

重要: サードパーティ Cookie が無効になっているモード B のブラウザで、サードパーティ Cookie のサポート終了に対するテストと準備を容易にするため、一時的にデバッグモードが利用可能です。モード B のブラウザの場合、enableDebugMode() を呼び出すと、デバッグ レポートが正常に有効になります。

privateAggregation.enableDebugMode({ <debugKey: debugKey> }) を呼び出してデバッグキーを設定することもできます。この場合、BigInt をデバッグキーとして使用できます。デバッグキーは、Cookie ベースの測定データとプライベート アグリゲーション測定のデータを関連付けるために使用できます。これらはコンテキストごとに 1 回だけ呼び出すことができます。後続の呼び出しは無視されます。

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

オーナー確認の報告

共有ストレージの場合は、共有ストレージ オペレーションの呼び出しにコンテキスト ID を追加することで、受け取った集計可能レポートが正当であることを確認できます。この ID は送信されたレポートに添付されます。後でこの ID を使用して、レポートが共有ストレージ オペレーションから送信されたものであることを確認できます。

この機能は Chrome M114 以降でテストできます。Protected Audience API のレポートの確認は、テストではまだご利用いただけません。

詳しくは、レポートの確認についての説明をご覧ください。

交流とフィードバックの共有

Private Aggregation API は現在検討中で、今後変更される可能性があります。この API を試してフィードバックがございましたら、ぜひお聞かせください。

• GitHub: 説明を読み、質問を投稿し、ディスカッションに参加します。
• デベロッパー サポート: プライバシー サンドボックス デベロッパー サポート リポジトリで質問したり、ディスカッションに参加したりできます。
• プライベート アグリゲーションに関する最新情報を入手するには、Shared Storage API グループと Protected Audience API グループにご参加ください。