Private Aggregation API の主なコンセプト
このドキュメントの対象者
Private Aggregation API クロスサイト データにアクセスできるワークレットから集約したデータ収集が可能です。 ここで紹介するコンセプトは、レポートを構築するデベロッパーにとって重要です。 Protected Audience API です。
- クロスサイト用のレポート システムを構築しているデベロッパーの場合 測定します
- マーケティング担当者、データ サイエンティスト、その他の概要レポートの場合 消費者、これらのメカニズムを理解することで、 最適化済み概要レポートを取得することもできます
主な用語
このドキュメントを読む前に、インフラストラクチャの 主な用語と概念について説明します。ここでは、それぞれの用語について詳しく説明します。
- 集計キー(バケットとも呼ばれます)は、 データポイントを収集できますたとえば ブラウザが国をレポートする場所データのバケット 表示されます。集計キーには複数のディメンション(例: 国や ID など)が含まれます。
- 集計可能な値は個々のデータポイント
集約キーに集約されます。新規ユーザーの数を
フランスのユーザーがコンテンツを閲覧した場合、
France
は次のディメンションのディメンションです。1
のviewCount
は集計可能な値です。 - 集計可能レポートは、ブラウザ内で生成され、暗号化されます。対象: Private Aggregation API: 単一のイベントに関するデータが含まれます。
- 集計サービス 集計可能レポートのデータを処理して概要レポートを作成します。
- 概要レポートは、集計サービスの最終出力です。 ノイズの多い集計ユーザーデータと詳細なコンバージョン データが含まれている。
- ワークレットは、 特定の JavaScript 関数を実行し、 リクエスト元に情報を返します。ワークレット内では 外部ページとの通信や通信はできません。
プライベート アグリゲーションのワークフロー
集計キーと UDM イベントを指定して Private Aggregation API を 集計可能値を指定すると、ブラウザは集計可能レポートを生成します。レポート 一括処理を行うサーバーに送られます一括処理されたレポートは 集計サービスによって後で処理され、概要レポートが生成されます。
![クライアントからコレクタ、そしてアグリゲーションへと続くデータフロー
概要レポートを生成するサービス。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=0000&hl=ja)
- Private Aggregation API を呼び出すと、クライアント(ブラウザ)によって 集計可能レポートをサーバーに送信して収集します。
- サーバーがクライアントからレポートを収集してバッチ処理し、 集計サービスに送信されます
- 十分な数のレポートを収集したら、バッチ処理して 高信頼実行環境で実行され、Google Cloud Storage 概要レポートを作成します
このセクションで説明するワークフローは、アトリビューション レポート API。ただし、 レポートでは、インプレッション イベントとコンバージョンから収集されたデータが関連付けられる 異なるタイミングで発生します。プライベートアグリゲーションでは 測定します
集計キー
集計キー(略して「キー」)は、集計対象となるバケットを 集計可能な値が累積されます1 つ以上のディメンションをエンコードできます。 渡します。ディメンションは、さらに取得したい側面を表します ユーザーの年齢層や広告のインプレッション数など あります
たとえば、複数のサイトに埋め込まれたウィジェットがあり、 ウィジェットを見たユーザーの国を分析できます。検索中 たとえば “私のウィジェットを見たユーザーの数 どこから来たんですか?」この質問に関するレポートを作成するには、集計キーを設定します 2 つのディメンション(ウィジェット ID と国 ID)をエンコードしています。
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}
はハッシュ化して
次の値 BigInt
:
42943797454801331377966796057547478208888578253058197330928948081739249096287n
。
ハッシュ値が 128 ビットを超える場合は、切り捨てられないように短縮できます。
バケットの最大許容値 2^128−1
を超えています。
共有ストレージ ワークレットでは、
crypto
、
TextEncoder
モジュール
ハッシュ値を生成できますハッシュの生成について詳しくは、以下をご覧ください。
SubtleCrypto.digest()
オン
MDN。
次の例は、ハッシュ化された鍵ファイルからバケットキーを生成する方法を 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 | 視聴回数 |
3,276 | 061 | 1 |
この例では、ウィジェットを表示するユーザーごとに値を 1 ずつ増やしています。 実際には、集計可能な値を調整することで、信号雑音比を改善できます。 比率。
掛金の予算
Private Aggregation API への各呼び出しは、コントリビューションと呼ばれます。データを保護するには ユーザーのプライバシー、 制限されています。
すべての集計キーの集計可能な値を合計する場合は、 資金提供の予算より低くする必要があります予算の範囲はワークレットごとに設定される origin、1 日あたり Protected Audience API と共有ストレージのワークレットは別個のものです。ローリング ウィンドウが使用されます。新しい 予算を超過すると、集計可能レポートは予算を超過し、 作成されます。
寄付予算はパラメータ L1 で表され、 バックストップは 220、1 日あたり 10 分あたり 216(65,536)に設定
(1,048,576)。詳しくは、 説明 パラメータの詳細をご覧ください。
寄与の予算の値は任意ですが、ノイズはその値にスケーリングされます。 この予算を使用して、サマリー値の信号対雑音比を最大化できます (詳しくは、ノイズとスケーリングのセクションをご覧ください)。
寄付の予算について詳しくは、 explainer。 寄付 予算 をご覧ください。
集計可能レポート
ユーザーが 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
ページ:
![Private Aggregation API の内部ページのスクリーンショット](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=0000&hl=ja)
テスト目的で [Send Selected Reports] のボタンをクリックすると、 サーバーにレポートが送信されます。
集計可能レポートを収集してバッチ処理する
ブラウザが集計可能レポートをワークレットの起点に送信する Private Aggregation API の呼び出しを含む path:
- 共有ストレージの場合:
/.well-known/private-aggregation/report-shared-storage
- Protected Audience の場合:
/.well-known/private-aggregation/report-protected-audience
これらのエンドポイントでは、コレクタとして機能するサーバーを運用する必要があります。 クライアントから送信された集計可能レポートを受信します。
サーバーはレポートをバッチ処理し、そのバッチを集計サービスに送信する
。暗号化されていない状態で入手可能な情報に基づいてバッチを作成します。
集計可能レポートのペイロード(shared_info
フィールドなど)。次のことが理想的です。
バッチごとに 100 件以上のレポートが含まれている必要があります。
毎日または毎週の単位でバッチ処理できます。この戦略は柔軟であり、 また、予想される特定のイベントのバッチ処理戦略を変更できます。 ボリュームの増加(例: インプレッション数が増加することが予想される日) バッチには、同じ API バージョン、レポート生成元、 スケジュール設定できます。
集計サービス
![このサービスは TEE で実行され、集計可能レポートを復号し、
ノイズを追加して、最終的な概要レポートを作成します。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=0000&hl=ja)
集計サービス 暗号化された集計可能レポートをコレクタから受信し、サマリーを生成する できます。
レポート ペイロードを復号するために、集計サービスは復号鍵をフェッチします。 示されます。高信頼実行環境(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 比はかなり高くなります
したがって、集計可能な値にスケーリング ファクタを乗算すると、 ノイズを低減します。スケーリング ファクタは、特定のイベントをどの程度スケーリングするかを 集計可能値を指定します
![集計値に関係なく、ノイズは一定です。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=0000&hl=ja)
スケーリング ファクタを大きくして値をスケールアップすると、 ノイズを軽減できます。ただし、この場合、すべてのバケットにわたるすべての貢献度の合計も発生します。 寄付の予算の上限に早く到達します値をスケールダウンする 小さいスケーリング ファクタ定数を選択すると、相対ノイズは増加しますが、 予算の上限に達するリスクを低減できます
![集計可能な値を資金提供の予算に合わせて調整します。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=0000&hl=ja)
適切なスケーリング ファクタを計算するには、分担予算を すべてのキーにわたる集計可能な値の最大合計。
詳しくは、寄付予算の ドキュメント をご覧ください。
対応してフィードバックを共有する
Private Aggregation API は現在検討中であり、今後変更される可能性があります。 実現します。この API をお試しいただき、ご意見やご感想がございましたら、ぜひお聞かせください。
- GitHub: explainer、 質問の投稿や、 ディスカッションできます。 * デベロッパー サポート: プライバシー サンドボックス デベロッパー サポート リポジトリをご覧ください。 * Shared Storage API に参加する グループ Protected Audience API グループ をご覧ください。