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

Private Aggregation API の概要

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

ウェブが依存する重要な機能を提供するため、Private Aggregation API は、プライバシーを保護した方法でクロスサイトデータを集計し、レポートに記録するよう設計されています。

実装ステータス

提案	ステータス
Shared Storage のレポート検証で Private Aggregation API の無効なレポートを防ぐ説明	Chrome で利用可能
3PC の利用資格に応じて非公開集計のデバッグモードの可用性が異なる GitHub の問題	Chrome M119 で利用可能
報告の遅延を短縮説明	Chrome M119 で利用可能
共有ストレージの Private Aggregation の送信タイムアウト説明	M119 で利用可能
Google Cloud の Private Aggregation API と Aggregation Service のサポート説明	Chrome M121 で利用可能
集計可能レポートペイロードのパディング説明	Chrome M119 で利用可能
auctionReportBuyers レポートで利用できる Private Aggregation デバッグモード説明	Chrome M123 で利用可能
フィルタ ID のサポート説明	Chrome M128 で利用可能
クライアントサイドの投稿の統合説明	Chrome M129 で利用可能
コンテキストごとの貢献の上限説明	2025 年第 1 四半期に予定
さまざまな測定ユースケースにプライバシーバジェットを事前に割り当てる名前付きプライバシーバジェット説明	2025 年第 2 四半期に予定
サードパーティ Cookie に依存せずに実装の問題をデバッグする集約エラーレポート説明	2025 年第 2 四半期に予定

Private Aggregation API とは

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

この API のメイン関数は contributeToHistogram() と呼ばれます。ヒストグラムオペレーションを使用すると、定義した各バケット（API では集計キーと呼ばれます）のユーザー間でデータを集計できます。ヒストグラム呼び出しは値を集計し、ノイズが追加された集計結果を概要レポートの形式で返します。たとえば、各ユーザーがコンテンツを閲覧したサイトの数や、サードパーティスクリプトでバグが発生した回数などがレポートに表示されます。このオペレーションは別の API のワークレット内で実行されます。

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

主なコンセプト

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

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

Private Aggregation API に関連する主なコンセプトについて詳しくは、Private Aggregation API の基本をご覧ください。

アトリビューションレポートとの違い

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

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

この API をテストする

Private Aggregation API をローカルでテストするには、chrome://settings/adPrivacy で広告のプライバシー API をすべて有効にします。

テストの詳細については、テストに参加するをご覧ください。

デモを使用する

Shared Storage 用 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 を使用すると、Shared Storage に保存されているクロスサイトデータを測定できます。

ユニークリーチの測定

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

共有ストレージにフラグを設定して、ユーザーがコンテンツをすでに見たかどうかを示すことができます。フラグが存在しない最初のアクセスでは、プライベートアグリゲーションの呼び出しが行われ、フラグが設定されます。ユーザーがその後アクセスしたとき（クロスサイトアクセスを含む）、共有ストレージを確認し、フラグが設定されていれば Private Aggregation へのレポートの送信をスキップできます。これらの測定を実装する方法については、リーチに関するホワイトペーパーをご覧ください。

ユーザー属性の測定

さまざまなサイトでコンテンツを閲覧したユーザーの属性を測定したい場合があります。

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

K 回以上のフリークエンシーの測定

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

プライベート集計では、「約 89 人のユーザーがコンテンツ ID 581 を 3 回以上視聴しました」などの回答を得ることができます。カウンタは、異なるサイトから共有ストレージ内でインクリメントでき、ワークレット内で読み取ることができます。カウントが K に達すると、プライベート集計を使用してレポートを送信できます。

マルチタッチアトリビューション

マーケティングアトリビューションとは、広告主がマーケティング戦略とそれに続く広告インタラクションが売上やコンバージョンにどれだけ貢献したかを判断するために使用する手法です。

Protected Audience API を使用する場合

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

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

使用可能な関数

次の関数は、Shared Storage と Protected Audience API ワークレットで使用できる privateAggregation オブジェクトで使用できます。

contributeToHistogram()

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

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

`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 sharedStorage.get(key) === 'true';

    // Don't 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

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

contributeToHistogramOnEvent()

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

privateAggregation.contributeToHistogramOnEvent(eventType, contribution) メソッドは、トリガーイベントを指定する eventType と、イベントがトリガーされたときに送信される contribution を受け取ります。トリガーイベントは、オークション終了後のオークション自体（オークションの落札イベントや落札失敗イベントなど）から発生する場合と、広告をレンダリングしたフェンス付きフレームから発生する場合があります。

オークションイベントのレポートを送信するには、2 つの予約済みキーワード reserved.win、reserved.loss、reserved.always を使用できます。フェンス付きフレームのイベントによってトリガーされたレポートを送信するには、カスタムイベントタイプを定義します。フェンス付きフレームからイベントをトリガーするには、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 ベースの測定と Private Aggregation の測定を比較する際に役立ちます。また、API 統合をすばやく検証することもできます。

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

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

privateAggregation.enableDebugMode({ <debugKey: debugKey> }) を呼び出してデバッグキーを設定することもできます。この場合、BigInt をデバッグキーとして使用できます。デバッグキーを使用すると、Cookie ベースの測定データと Private Aggregation の測定データを関連付けることができます。

これらはコンテキストごとに 1 回だけ呼び出すことができます。後続の呼び出しは例外をスローします。

// Enables debug mode
privateAggregation.enableDebugMode();

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

レポートの確認

Private Aggregation API を使用すると、ユーザーのプライバシーを保護しながら、サイトをまたいだ測定を行うことができます。ただし、悪意のある行為者がこれらの測定の精度を操作しようとする可能性があります。これを防ぐには、コンテキスト ID を使用してレポートの信頼性を確認します。

コンテキスト ID を設定すると、最終的な集計結果に貢献する際にデータが正確であることを確認できます。これは、次の方法で実現されます。

不正なレポートや偽のレポートを防ぐ: レポートが正当な API 呼び出しによって生成されたことを確認し、悪意のあるユーザーがレポートを偽造することを困難にします。
レポートの再利用の防止: 古いレポートの再利用を試みる行為を検出し、拒否することで、各レポートが 1 回だけ集計結果に反映されるようにします。

共有ストレージ

集計可能なレポートを送信できるオペレーションを実行するために共有ストレージを使用する場合、ワークレットの外部で予測不可能な ID を設定できます。

この ID は、ワークレットから作成されたレポートに埋め込まれます。run() または selectURL() 共有ストレージメソッドを呼び出すときに、privateAggregationConfig キーの下のオプションオブジェクト内で指定できます。

次に例を示します。

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

この ID を設定すると、レポートが共有ストレージオペレーションから送信されたことを確認するために使用できます。情報漏洩を防ぐため、contributeToHistogram() 呼び出しの回数に関係なく、共有ストレージオペレーションごとに 1 つのレポートが送信されます（コントリビューションが行われなかった場合でも）。

Private Aggregation API は、最大 1 時間のランダムな遅延を伴って集計可能レポートを送信します。ただし、レポートを検証するコンテキスト ID を設定すると、この遅延が短縮されます。この場合、共有ストレージオペレーションの開始から 5 秒の固定された短い遅延が発生します。

ワークフローの例（上の図を参照）:

共有ストレージオペレーションが、コンテキスト ID を指定する Private Aggregation 構成で実行され、集計可能レポートが生成されます。
コンテキスト ID は、サーバーに送信される生成済みの集計可能レポートに埋め込まれます。
サーバーは生成された集計可能レポートを収集します。
サーバー上のプロセスは、各集計可能レポートのコンテキスト ID を保存済みのコンテキスト ID と照合して有効性を確認してから、レポートをバッチ処理して集計サービスに送信します。

コンテキスト ID の確認

コレクタサーバーへの受信レポートは、集計サービスに送信される前に、いくつかの方法で検証できます。コンテキスト ID が次のいずれかに該当する場合、コンテキスト ID が無効なレポートは拒否されることがあります。

不明: システムで作成されていないコンテキスト ID を含むレポートが届いた場合は、破棄できます。これにより、不明なアクターや悪意のあるアクターが、集計パイプラインにデータを挿入することを防ぎます。
重複: 同じコンテキスト ID のレポートが 2 つ以上届いた場合は、破棄するレポートを選択する必要があります。
スパム検出でフラグが付けられた:
- ユーザーのレポートを処理しているときに、ユーザーの不審なアクティビティ（ユーザーのアクティビティの急激な変化など）を検出した場合は、レポートを破棄できます。
- レポートは、コンテキスト ID や関連するシグナル（ユーザーエージェント、参照元など）とともに保存できます。後で、ユーザーの行動を分析して新しいスパム指標を特定したら、関連付けられたコンテキスト ID とシグナルに基づいて、保存されたレポートを再評価できます。これにより、ユーザーからの報告が最初にフラグ付けされていなくても、不審なアクティビティを示しているユーザーからの報告を破棄できます。

意見交換とフィードバックの提供

Private Aggregation API は現在、活発な議論の途上にあり、今後変更される可能性があります。この API をお試しになり、フィードバックがございましたら、ぜひお聞かせください。

GitHub: 解説の確認、質問の投稿、意見交換への参加を行えます。
デベロッパーサポート: プライバシーサンドボックスデベロッパーサポートリポジトリで質問や意見交換を行えます。
Private Aggregation に関する最新のお知らせについては、Shared Storage API グループと Protected Audience API グループにご参加ください。