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

Private Aggregation API の概要

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

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

実装ステータス

提案	状态
通过对共享存储空间的报告进行验证，防止 Private Aggregation API 报告无效说明	在 Chrome 中提供
私有汇总调试模式的可用性取决于 3PC 资格条件 GitHub 问题	适用于 Chrome M119
缩短报告延迟时间说明	适用于 Chrome M119
共享存储空间的不公开汇总贡献超时说明	适用于 M119
支持 Google Cloud 专用汇总 API 和汇总服务说明	适用于 Chrome M121
可汇总报告载荷的填充说明	适用于 Chrome M119
私密汇总调试模式适用于 auctionReportBuyers 报告说明	适用于 Chrome M123
过滤 ID 支持说明	适用于 Chrome M128
客户端贡献合并说明	适用于 Chrome M129

Private Aggregation API とは

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

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

たとえば、以前に Shared Storage にユーザー属性と地域データを記録している場合は、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 を有効にします。

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

デモを使用する

共有ストレージ用の 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 は、「Content ID 861 を視聴したユニークユーザーは約 317 人です」などの回答を提供できます。

共有ストレージにフラグを設定して、ユーザーがコンテンツをすでに視聴したかどうかを示すことができます。フラグが存在しない初回アクセス時に、非公開集計が呼び出され、フラグが設定されます。ユーザーがサイトをまたいでアクセスするなど、その後のアクセスでは、共有ストレージをチェックし、フラグが設定されている場合はプライベート集計へのレポートの送信をスキップできます。これらの測定を実装する方法について詳しくは、リーチのホワイトペーパーをご覧ください。

ユーザー属性の測定

さまざまなサイトでコンテンツを視聴したユーザーの属性を測定したい場合。

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

1,000 回以上のフリークエンシーの測定

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

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

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

このガイダンスは、広告テクノロジーが共有ストレージと非公開集計内で MTA を実装する方法を理解できるように、デベロッパーサイトに公開されます。

Protected Audience API を使用

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

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

使用可能な関数

次の関数は、Shared Storage 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 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 を受け取ります。トリガーイベントは、オークションの終了後にオークション自体から発生するイベント（オークションの落札または落札失敗イベントなど）である場合もあれば、広告をレンダリングしたフェンスドフレームから発生するイベントである場合もあります。

オークションイベントのレポートを送信するには、reserved.win、reserved.loss、reserved.always の 3 つの予約済みキーワードを使用できます。フェンスされたフレームのイベントによってトリガーされたレポートを送信するには、カスタムイベントタイプを定義します。フェンスドフレームからイベントをトリガーするには、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() を呼び出すと、デバッグモードが有効になり、集計可能なレポートに暗号化されていない（クリアテキスト）ペイロードが含まれます。これらのペイロードは、Aggregation Service のローカルテストツールで処理できます。

デバッグモードは、サードパーティ Cookie へのアクセスを許可されている呼び出し元にのみ使用できます。呼び出し元がサードパーティ Cookie にアクセスできない場合、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) });

報告の確認

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

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

不正な報告や不正な報告の防止: レポートが正当で信頼できる API 呼び出しによって生成されるようにし、不正な行為者による報告の偽造を困難にします。
レポートの再実行を防止: 古いレポートの再利用を検出して拒否し、各レポートが集計結果に 1 回だけ貢献するようにします。

共有ストレージ

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

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

次に例を示します。

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

この ID を設定すると、この 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 グループに参加してください。