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

Private Aggregation API の基礎

Private Aggregation API の主なコンセプト

このドキュメントの対象者

Private Aggregation API を使用すると、クロスサイトデータにアクセスできるワークレットから集計データを収集できます。ここで説明するコンセプトは、Shared Storage API と Protected Audience API 内でレポート機能を構築するデベロッパーにとって重要です。

クロスサイト測定用のレポートシステムを構築しているデベロッパー。
マーケティング担当者、データサイエンティスト、その他の概要レポートの利用者は、これらのメカニズムを理解することで、最適化された概要レポートを取得するための設計上の決定を下すことができます。

主な用語

このドキュメントを読む前に、重要な用語とコンセプトを理解しておくことをおすすめします。これらの用語について、以下で詳しく説明します。

集計キー（バケット）は、事前に定義されたデータポイントの集合です。たとえば、ブラウザが国名を報告する位置情報のバケットを収集できます。集計キーには複数のディメンション（コンテンツウィジェットの国と ID など）を含めることができます。
集計可能な値は、集計キーに収集される個々のデータポイントです。フランスのユーザーがコンテンツを見た回数を測定する場合、France は集計キーのディメンションで、1 の viewCount は集計可能な値です。
集計可能レポートは、ブラウザ内で生成され、暗号化されます。Private Aggregation API の場合、単一のイベントに関するデータが含まれます。
集計サービスは、集計可能レポートのデータを取り込み、概要レポートを作成します。
サマリーレポートは、集計サービスの最終的な出力で、ノイズの多い集計されたユーザーデータと詳細なコンバージョンデータが含まれています。
ワークレットは、特定の JavaScript 関数を実行してリクエスト元に情報を返すことができるインフラストラクチャの一部です。ワークレット内では JavaScript を実行できますが、外部ページとのやり取りや通信はできません。

Private Aggregation ワークフロー

集計キーと集計可能な値を指定して Private Aggregation API を呼び出すと、ブラウザは集計可能なレポートを生成します。レポートは、レポートをバッチ処理するサーバーに送信されます。バッチ処理されたレポートは、後で集計サービスによって処理され、概要レポートが生成されます。

データはクライアントからコレクタに送られ、次に集計サービスに送られて概要レポートが生成されます。

Private Aggregation API を呼び出すと、クライアント（ブラウザ）が集計可能なレポートを生成し、収集のためにサーバーに送信します。
サーバーはクライアントからレポートを収集し、バッチ処理して集計サービスに送信します。
十分な数のレポートを収集したら、それらをバッチ処理して信頼できる実行環境で実行されている集計サービスに送信し、概要レポートを生成します。

このセクションで説明するワークフローは、Attribution Reporting API と類似しています。ただし、アトリビューションレポートでは、発生するタイミングが異なるインプレッションイベントとコンバージョンイベントから収集されたデータが関連付けられます。プライベートアグリゲーションでは、単一のクロスサイトイベントが測定されます。

集計キー

集計キー（略して「キー」）は、集計可能な値が蓄積されるバケットを表します。1 つ以上のディメンションをキーにエンコードできます。ディメンションは、ユーザーの年齢層や広告キャンペーンのインプレッション数など、詳細な分析情報を得たい項目を表します。

たとえば、複数のサイトに埋め込まれたウィジェットがあり、そのウィジェットを見たユーザーの国を分析したい場合などです。「ウィジェットを見たユーザーのうち、国 X のユーザーは何人ですか？」などの質問に回答したい場合。この質問に関するレポートを作成するには、ウィジェット ID と国 ID の 2 つのディメンションをエンコードする集計キーを設定します。

Private Aggregation API に指定するキーは BigInt で、複数のディメンションで構成されます。この例では、ディメンションはウィジェット ID と国 ID です。ウィジェット ID は最大 4 桁（1234 など）で、各国はアルファベット順で番号にマッピングされます（アフガニスタンは 1、フランスは 61、ジンバブエは 195 など）。したがって、集計可能なキーは 7 桁で、最初の 4 桁は WidgetID 用に予約され、最後の 3 桁は CountryID 用に予約されます。

キーが、ウィジェット ID 3276 を見たフランスのユーザー（国 ID 061）の数を表すとします。集計キーは 3276061 です。

集計キー
ウィジェット ID	国 ID
3276	061

例: ディメンションに複数桁のキースペースが使用可能で、値がそれより少ない場合は、先頭にゼロを追加します。たとえば、国 ID が 3 桁の場合、アルジェリアの国 ID は 003 です。

集計キーは、SHA-256 などのハッシュ化メカニズムを使用して生成することもできます。たとえば、文字列 {"WidgetId":3276,"CountryID":67} をハッシュしてから、42943797454801331377966796057547478208888578253058197330928948081739249096287n の BigInt 値に変換できます。ハッシュ値が 128 ビットを超える場合は、バケット値の最大許容値 2^128−1 を超えないように切り捨てることができます。

共有ストレージワークレット内では、ハッシュの生成に役立つ crypto モジュールと TextEncoder モジュールにアクセスできます。ハッシュの生成の詳細については、MDN の SubtleCrypto.digest() をご覧ください。

次の例は、ハッシュ化された値からバケットキーを生成する方法を示しています。

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 時間程度のローリングウィンドウが使用されます。新しい集計レポートによって予算が超過する場合、レポートは作成されません。

コントリビューションバジェットはパラメータ L₁ で表され、1 日 10 分あたり 2¹⁶（65,536）に設定され、2²⁰（1,048,576）のバックストップを設定します。これらのパラメータの詳細については、説明をご覧ください。

コントリビューションバジェットの値は任意ですが、ノイズはそれに比例してスケーリングされます。この予算を使用して、サマリー値の信号対雑音比を最大化できます（ノイズとスケーリングのセクションで詳しく説明します）。

コントリビューションバジェットについて詳しくは、説明をご覧ください。また、拠出金予算も参照してください。

レポートあたりの貢献度上限

拠出限度額は、呼び出し元によって異なる場合があります。現在のところ、Shared Storage API 呼び出し元に対して生成されるレポートは、レポートごとに 20 件の寄付に制限されています。一方、Protected Audience API 呼び出し元は、レポートあたり 100 件の貢献に制限されています。これらの上限は、埋め込むことができる投稿の数とペイロードのサイズのバランスを取るために選択されています。

共有ストレージの場合、単一の run() オペレーションまたは selectURL() オペレーション内で行われた貢献は、1 つのレポートにバッチ処理されます。Protected Audience の場合、オークション内の単一のオリジンによる貢献はまとめてバッチ処理されます。

パディングありの投稿

寄付は、パディング機能によってさらに変更されます。ペイロードをパディングすることで、集計可能なレポートに埋め込まれた実際の寄付数に関する情報が保護されます。パディングでは、null のコントリビューション（値 0）でペイロードを拡張して、固定長に達します。

集計可能レポート

ユーザーが Private Aggregation API を呼び出すと、ブラウザは集計可能なレポートを生成します。このレポートは、後で集計サービスによって処理され、サマリーレポートが生成されます。集計可能なレポートは JSON 形式で、暗号化された貢献リストが含まれます。各貢献は {aggregation key, aggregatable value} ペアです。集計可能レポートは、最大 1 時間のランダムな遅延で送信されます。

投稿は暗号化され、Aggregation Service の外部からは読み取れません。集計サービスはレポートを復号し、概要レポートを生成します。ブラウザの暗号鍵と集約サービスの復号鍵は、鍵管理サービスとして機能するコーディネーターによって発行されます。コーディネーターは、サービスイメージのバイナリハッシュのリストを保持し、呼び出し元が復号鍵を受信できることを確認します。

デバッグモードが有効になっている集計可能なレポートの例:

  "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 ページで確認できます。

テスト目的で、[選択したレポートを送信] ボタンを使用して、レポートをすぐにサーバーに送信できます。

集計可能レポートを収集してバッチ処理する

ブラウザは、リストに記載されている 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）で実行されます。サービスは所有して運用しますが、TEE 内で処理されるデータは可視化されません。

概要レポート

概要レポートでは、収集したデータにノイズが追加されたデータを確認できます。特定のキーセットの概要レポートをリクエストできます。

概要レポートには、JSON 辞書形式の Key-Value ペアのセットが含まれています。各ペアには次のものが含まれます。

bucket: バイナリ数値文字列としての集計キー。使用される集計キーが「123」の場合、バケットは「1111011」になります。
value: 特定の測定目標の概要値。利用可能なすべての集計可能レポートから合計され、ノイズが追加されています。

次に例を示します。

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

ノイズとスケーリング

ユーザーのプライバシーを保護するため、集計サービスは、概要レポートがリクエストされるたびに、各概要値にノイズを 1 回追加します。ノイズ値はラプラス確率分布からランダムに抽出されます。ノイズの追加方法を直接制御することはできませんが、測定データへのノイズの影響を軽減することはできます。

ノイズ分布は、集計可能なすべての値の合計に関係なく同じです。したがって、集計可能な値が大きいほど、ノイズの影響は小さくなります。

たとえば、ノイズ分布の標準偏差が 100 で、中心がゼロであるとします。収集された集計可能なレポート値（「集計可能な値」）が 200 に過ぎない場合、ノイズの標準偏差は集計値の 50% になります。ただし、集計可能な値が 20,000 の場合、ノイズの標準偏差は集計値の 0.5% にすぎません。したがって、集計可能な値が 20,000 の場合、信号対雑音比は大幅に高くなります。

したがって、集計可能な値にスケーリングファクタを掛けると、ノイズを低減できます。スケール係数は、特定の集計可能な値をスケーリングする量を表します。

より大きなスケーリング係数を選択して値をスケールアップすると、相対的なノイズが低減されます。ただし、これにより、すべてのバケットのすべての拠出の合計が、拠出予算の上限に早く達することになります。小さいスケーリング係数定数を選択して値をスケールダウンすると、相対ノイズが増加しますが、予算の上限に達するリスクは軽減されます。

適切なスケーリングファクタを計算するには、コントリビューションバジェットを、すべてのキーの集計可能な値の最大合計で割ります。

詳しくは、コントリビューションバジェットのドキュメントをご覧ください。

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

Private Aggregation API は現在検討中であり、今後変更される可能性があります。この API をお試しになった際のフィードバックをお寄せください。

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