Private Aggregation API の主なコンセプト
このドキュメントの対象者
Private Aggregation API を使用すると、クロスサイト データにアクセスできるワークレットから集計データを収集できます。ここで紹介するコンセプトは、レポートを構築するデベロッパーにとって重要です。 Protected Audience API です。
- クロスサイト用のレポート システムを構築しているデベロッパーの場合 測定します
- マーケティング担当者、データ サイエンティスト、その他の概要レポートの場合 消費者、これらのメカニズムを理解することで、 最適化済み概要レポートを取得することもできます
主な用語
このドキュメントを読む前に、重要な用語とコンセプトを理解しておくことをおすすめします。これらの用語について、以下で詳しく説明します。
- 集計キー（バケット）は、事前に定義されたデータポイントの集合です。たとえば、ブラウザが国名を報告する位置情報のバケットを収集できます。集計キーには複数のディメンション（例: 国や ID など）が含まれます。
- 集計可能な値は個々のデータポイント
集約キーに集約されます。フランスのユーザーがコンテンツを見た回数を測定する場合、
Franceは集計キーのディメンションで、1のviewCountは集計可能な値です。 - 集計可能レポートは、ブラウザ内で生成され、暗号化されます。Private Aggregation API の場合、単一のイベントに関するデータが含まれます。
- 集計サービス 集計可能レポートのデータを処理して概要レポートを作成します。
- 概要レポートは、集計サービスの最終出力です。 ノイズの多い集計ユーザーデータと詳細なコンバージョン データが含まれている。
- ワークレットは、特定の JavaScript 関数を実行してリクエスト元に情報を返すことができるインフラストラクチャの一部です。ワークレット内では JavaScript を実行できますが、外部ページとのやり取りや通信はできません。
プライベート アグリゲーションのワークフロー
集計キーと UDM イベントを指定して Private Aggregation API を ブラウザによって集計可能レポートが生成されます。レポートは、レポートをバッチ処理するサーバーに送信されます。バッチ処理されたレポートは、後で集計サービスによって処理され、概要レポートが生成されます。
- Private Aggregation API を呼び出すと、クライアント（ブラウザ）によって 集計可能レポートをサーバーに送信して収集します。
- サーバーがクライアントからレポートを収集してバッチ処理し、 集計サービスに送信されます
- 十分な数のレポートを収集したら、それらをバッチ処理して信頼できる実行環境で実行されている集計サービスに送信し、概要レポートを生成します。
このセクションで説明するワークフローは、Attribution Reporting API に似ています。一方、アトリビューション レポートでは、異なるタイミングで発生するインプレッション イベントとコンバージョン イベントから収集されたデータが関連付けられます。プライベート アグリゲーションでは、単一のクロスサイト イベントが測定されます。
集計キー
集計キー（略して「キー」）は、集計可能な値が蓄積されるバケットを表します。1 つ以上のディメンションをエンコードし 渡します。ディメンションは、さらに取得したい側面を表します ユーザーの年齢層や広告のインプレッション数など あります
たとえば、複数のサイトに埋め込まれたウィジェットがあり、そのウィジェットを見たユーザーの国を分析したい場合などです。検索中 たとえば “私のウィジェットを見たユーザーの数 どこから来たんですか？」この質問に関するレポートを作成するには、ウィジェット ID と国 ID の 2 つのディメンションをエンコードする集計キーを設定します。
Private Aggregation API に指定するキーは BigInt で、複数のディメンションで構成されます。この例のディメンションは
ウィジェット ID と国 ID ですウィジェット ID は最大 4 桁（1234 など）で、各国はアルファベット順で番号にマッピングされているとします。たとえば、アフガニスタンは 1、フランスは 61、ジンバブエは「195」です。したがって、集計可能なキーは 7 桁で、最初の 4 桁は WidgetID 用に予約され、最後の 3 桁は CountryID 用に予約されます。
たとえば、キーがフランス（国 ID 061）のユーザー数を表すとします。
3276、集計キーは3276061です。
| 集計キー | |
| ウィジェット ID | 国 ID |
| 3,276 | 061 |
集計キーは、次のようなハッシュ メカニズムを使用して生成することもできます。
SHA-256。たとえば、文字列 {"WidgetId":3276,"CountryID":67} をハッシュしてから、42943797454801331377966796057547478208888578253058197330928948081739249096287n の BigInt 値に変換できます。ハッシュ値が 128 ビットを超える場合は、切り捨てられないように短縮できます。
バケットの最大許容値 2^128−1 を超えています。
共有ストレージ ワークレット内では、ハッシュの生成に役立つ crypto モジュールと TextEncoder モジュールにアクセスできます。ハッシュの生成の詳細については、MDN の SubtleCrypto.digest() をご覧ください。
次の例は、ハッシュ化されたファイルからバケットキーを生成する方法について value:
async function convertToBucket(data) {
// Encode as UTF-8 Uint8Array
const encodedData = new TextEncoder().encode(data);
// Generate SHA-256 hash
const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);
// Truncate the hash
const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));
// Convert the byte sequence to a decimal
return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}
const data = {
WidgetId: 3276,
CountryID: 67
};
const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);
console.log(bucket); // 126200478277438733997751102134640640264n
集計可能な値
集計可能な値は、多くのユーザーのキーごとに合計され、集計レポートの概要値の形で集計された分析情報が生成されます。
前述の質問例「ウィジェットを見たユーザーのうち、フランスからのユーザーは何人ですか？」に戻りましょう。この質問の答えは 「私のウィジェット ID 3276 を見た約 4,881 人のユーザーが フランスの料理です。」集計可能な値は、ユーザーごとに 1、「4, 881 人のユーザー」です。 集計されたすべての集計可能な値の合計である、集計値 集計キー。
| 集計キー | 集計可能な値 | |
| ウィジェット ID | 国 ID | 視聴回数 |
| 3276 | 061 | 1 |
この例では、ウィジェットを表示したユーザーごとに値を 1 ずつ増やします。実際には、集計可能な値をスケーリングして信号対雑音比を改善できます。
掛金の予算
Private Aggregation API への各呼び出しは、コントリビューションと呼ばれます。データを保護するには ユーザーのプライバシー、 制限されています。
すべての集計キーの集計可能な値を合計する場合は、 資金提供の予算より低くする必要があります予算は、ワークレットのオリジンごとに 1 日あたりに設定され、Protected Audience API ワークレットと Shared Storage ワークレットで別々に設定されます。1 日には、過去 24 時間程度のローリング ウィンドウが使用されます。新しい 予算を超過すると、集計可能レポートは予算を超過し、 作成されます。
コントリビューション バジェットはパラメータ L1 で表され、1 日 10 分あたり 216（65,536）に設定され、220 のバックストップを設定します。
（1,048,576）。これらのパラメータの詳細については、説明をご覧ください。
コントリビューション バジェットの値は任意ですが、ノイズはそれに比例してスケーリングされます。この予算を使用して、サマリー値の信号対雑音比を最大化できます（ノイズとスケーリングのセクションで詳しく説明します）。
寄付の予算について詳しくは、 explainer。 寄付 予算 をご覧ください。
レポート 1 件あたりの貢献度の上限
拠出限度額は、呼び出し元によって異なる場合があります。現在のところ 最大 20 件のコントリビューションをレポートで使用できます。 一方、Protected Audience API の呼び出し元の上限は 100 件 レポートあたりこれらの上限は、埋め込むことができる投稿の数とペイロードのサイズのバランスを考慮して選択されています。
共有ストレージの場合、単一の run() または selectURL() 内で行われたコントリビューション
1 つのレポートにまとめられますProtected Audience では、寄付が
まとめてバッチ処理されます。
パディングありの投稿
寄付は、パディング機能によってさらに変更されます。スペースをパディングすることで、
ペイロードに埋め込まれたコントリビューションの本数に関する情報を保護
集計可能レポートが作成されますパディングは null コントリビューションでペイロードを拡張します。
（つまり、値 0 を指定）して固定長にします。
集計可能レポート
ユーザーが Private Aggregation API を呼び出すと、ブラウザは集計可能なレポートを生成します。このレポートは、後で集計サービスによって処理され、サマリー レポートが生成されます。集計可能なレポートは JSON 形式で、暗号化された貢献リストが含まれます。各貢献は {aggregation key, aggregatable value} ペアです。集計可能レポートは、最大 1 時間のランダムな遅延で送信されます。
コントリビューションは暗号化され、集計サービスの外部で読み取ることはできません。 集計サービスはレポートを復号し、概要レポートを生成します。「 ブラウザの暗号鍵と集計データの復号鍵の サービスは、鍵管理サービスとして機能するコーディネーターによって発行されます。 コーディネーターは、サービス イメージのバイナリハッシュのリストを保持し、呼び出し元が復号鍵を受信できることを確認します。
debug による集計可能レポートの例 モードを有効にします。
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
"payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
}
],
"debug_key": "777",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"
集計可能なレポートは、chrome://private-aggregation-internals ページで確認できます。
テスト目的で [Send Selected Reports] のボタンをクリックすると サーバーにすぐレポートが送信されます。
集計可能レポートを収集してバッチ処理する
ブラウザは、リストに記載されている well-known パスを使用して、集約可能なレポートを、Private Aggregation API の呼び出しを含むワークレットのオリジンに送信します。
- 共有ストレージの場合:
/.well-known/private-aggregation/report-shared-storage - Protected Audience の場合:
/.well-known/private-aggregation/report-protected-audience
これらのエンドポイントでは、クライアントから送信された集計可能レポートを受信するコレクタとして機能するサーバーを運用する必要があります。
サーバーはレポートをバッチ処理し、バッチを集計サービスに送信する必要があります。暗号化されていない状態で入手可能な情報に基づいてバッチを作成します。
集計可能レポートのペイロード（shared_info フィールドなど）。理想的には、バッチごとに 100 件以上のレポートを含める必要があります。
毎日または毎週の単位でバッチ処理できます。この戦略は柔軟性があり、より多くのボリュームが予想される特定のイベント（インプレッション数の増加が予想される日付など）に合わせてバッチ処理戦略を変更できます。バッチには、同じ API バージョン、レポート生成元、 スケジュール設定できます。
集計サービス
集計サービス 暗号化された集計可能レポートをコレクタから受信し、サマリーを生成する できます。
レポート ペイロードを復号するために、集計サービスはコーディネーターから復号鍵を取得します。このサービスは、データの整合性、データの機密性、コードの整合性について一定の保証を提供する高信頼実行環境（TEE）で実行されます。お客様がサービスを所有、運営していても、 TEE で処理されているデータを可視化します
概要レポート
概要レポートでは、収集したデータにノイズが追加されたデータを確認できます。こちらから 概要レポートも作成できます。
概要レポートには、JSON 辞書形式の Key-Value ペアのセットが含まれています。各ペアには次のものが含まれます。
bucket: 2 進数の文字列としての集計キー。もし 使用される集計キーは「123」、バケットは「1111011」です。value: 特定の測定目標の概要値。利用可能なすべての集計可能レポートから合計され、ノイズが追加されます。
例:
[
{"bucket":` `"111001001",` `"value":` `"2558500"},
{"bucket":` `"111101001",` `"value":` `"3256211"},
{"bucket":` `"111101001",` `"value":` `"6536542"},
]
ノイズとスケーリング
ユーザーのプライバシーを保護するため、集計サービスは 概要レポートがリクエストされるたびに発生します。ノイズ値は ラプラス確率分布からランダムに抽出されます。Google Cloud の ノイズの追加方法を直接制御することはできません。ノイズの追加方法に ノイズを除去できます。
ノイズ分布は、集計可能なすべての 使用できます。したがって、集計可能値が高いほど、ノイズの影響が小さくなります。 あります
たとえば、ノイズ分布の標準偏差が 100 であるとします。 0 を基準とします。収集された集計可能レポート値（または 「集計可能値」）が 200 しかない場合、ノイズの標準偏差は 総計値の 50% です。集計可能値が 20,000 の場合 ノイズの標準偏差は集計値の 0.5% にすぎないでしょう。したがって、 SN 比はかなり高くなります
したがって、集計可能な値にスケーリング ファクタを乗算すると、 ノイズを低減します。スケーリング ファクタは、特定のイベントをどの程度スケーリングするかを 集計可能値を指定します
より大きなスケーリング係数を選択して値をスケールアップすると、相対的なノイズが低減されます。ただし、この場合、すべてのバケットにわたるすべての貢献度の合計も発生します。 寄付の予算の上限に早く到達します値をスケールダウンする 小さいスケーリング ファクタ定数を選択すると、相対ノイズは増加しますが、 予算の上限に達するリスクを低減できます
適切なスケーリング ファクタを計算するには、コントリビューション バジェットを、すべてのキーの集計可能な値の最大合計で割ります。
詳しくは、寄付予算の ドキュメント をご覧ください。
対応してフィードバックを共有する
Private Aggregation API は現在検討中であり、今後変更される可能性があります。 実現します。この API をお試しになった際のフィードバックをお寄せください。
- GitHub: 説明を読み、質問を投稿し、ディスカッションに参加します。 * デベロッパー サポート: プライバシー サンドボックス デベロッパー サポート リポジトリで質問や意見交換を行えます。 * Shared Storage API グループと Protected Audience API グループに参加して、Private Aggregation に関する最新のお知らせをご確認ください。