広告テクノロジーが測定 API(Attribution Reporting API または Private Aggregation API)をトリガーすると、暗号化されたレポートが Chrome ブラウザまたはクライアント側から広告テクノロジーのレポート エンドポイント(広告テクノロジーのレポート元を含む .well-known
URL)に送信されます。レポート エンドポイントは、暗号化されたレポートを収集するために広告テクノロジーによってホストされます。
API ごとのエンドポイントは次のとおりです。
プライベート アグリゲーション
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
をデバッグする[reporting-origin]/.well-known/private-aggregation/report-shared-storage
または/.well-known/private-aggregation/report-protected-audience
のライブ配信
アトリビューション レポート
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
をデバッグする- ライブ
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
広告テクノロジーは、POST 呼び出しを介して JSON 形式のレポートを受け取ります。広告テクノロジーはこれらの JSON レポートを収集し、後で集計サービスで使用される AVRO 形式に変換します。変換された AVRO レポートは、後でバッチ処理できるように広告テクノロジーのクラウド ストレージに保存されます。
広告テクノロジーがバッチ処理の準備ができたら、広告テクノロジーは集計サービスを通じて集計ジョブ リクエストをトリガーします。そこでは、広告テクノロジーのクラウド ストレージからレポートが取得されます。集計サービスは広告テクノロジーのクラウド ストレージにホストされており、許可リストに登録された画像が必要です。
受け取ったレポートは次のようになります。
Private Aggregation API
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
"payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
}
Attribution Reporting API
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
"payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
} ],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
"source_debug_key": "123456789",
"trigger_debug_key": "123456789"
}
JSON を AVRO レポートに変換する
バッチ処理する場合、集計可能なレポートは AVRO 形式である必要があります。AVRO レポートを作成するには、レポート AVRO スキーマ(AVSC)が必要です。
JavaScript サンプルコードは、Aggregation Service GitHub リポジトリで入手できます。
すべてのレポートに 1 つの Avro ファイルを使用することも、レポートを複数の Avro ファイルに分割することもできます。AVRO のサイズに上限はありません。パフォーマンス上の理由から、AVRO ファイルの数は、Cloud インスタンスで使用可能な CPU の数と 1,000 の間の値にすることをおすすめします。
集計可能レポートの AVRO スキーマは次のとおりです。レポートのフィールドは payload
、key_id
、shared_info
です。
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
パラメータ | 型 | 説明 |
---|---|---|
payload |
バイト |
ライブ / 本番環境レポートでは、ペイロードを base64 でデコードし、payload のバイト配列に変換する必要があります。 |
debug_cleartext_payload |
バイト |
デバッグ レポートでは、ペイロードを base64 でデコードし、debug_cleartext_payload のバイト配列に変換する必要があります。 |
key_id |
文字列 | これは、レポートに表示される key_id 文字列です。key_id は、同様の 128 ビットのユニバーサルな一意の識別子です。 |
shared_info |
文字列 | これは、レポートの shared_info フィールドにある改ざんされていない文字列です。 |
レポート JSON の例を次に示します。
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [{
"debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX",
"key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
"payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq"
}],
"debug_key": "1234",
"shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}
出力ドメイン AVRO
集計サービスを使用して概要レポートを生成するには、広告テクノロジーに集計可能レポートとドメイン ファイルが必要です。集計可能レポートは、レポート送信元で受信され、AVRO 形式に変換された JSON レポートです。出力ドメインには、集計可能レポートから収集され、概要レポートに書き込まれる事前宣言キーが含まれます。これらのキーの詳細については、アトリビューション レポートのキーと非公開集計のキーをご覧ください。出力ドメインにはフィールド バケットが含まれ、バケット値はバケットキーになります。
ドメイン ファイルも、次のスキーマを使用して Avro 形式にする必要があります。
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. 128-bit integer encoded as a 16-byte big-endian bytestring."
}
]
}
バケットキー
バケットキーは、バケットキーの 16 進バイト文字列にする必要があります。たとえば、キーが 1369 の場合、10 進数で指定します。16 進数に変換すると 559 になります。次に、559 をバイト文字列に変換して、出力ドメイン AVRO に追加する必要があります。
バッチ レポート
プライバシー バジェットとバッチ処理について詳しくは、バッチ処理戦略のドキュメントをご覧ください。また、集計可能なレポートは、特定の期間内にのみバッチ処理できます。レポートの期間は、scheduled_report_time
とバッチ実行日との間の MAX_REPORT_AGE(現在は 90 日間)を超えてはなりません。
概要レポート
バッチ処理後、Aggregation Service は AVRO 形式の概要レポートを作成します。概要レポートでは、results.avsc
スキーマが使用されます。
概要レポートは、createJob
リクエストで指定された output_data_bucket_name
バケットの output_data_blob_prefix
に配置されます。
debug_run が有効になっている集計サービス バッチの場合、2 つのレポートが作成されます。サマリー レポートとデバッグ サマリー レポート。デバッグ概要レポートは output_data_blob_prefix/debug
フォルダにあります。
生成されたデバッグ レポートは debug_results.avsc
スキーマを使用します。
概要レポートとデバッグ レポートの名前は [output_data_blob_prefix]-1-of-1.avro
になります。output_data_blob_prefix が summary/summary.avro
の場合、レポートは summary フォルダに summary-1-of-1.avro
という名前で保存されます。
results.avsc
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "metric",
"type": "long",
"doc": "Metric associated with the bucket"
}
]
}
debug_results.avsc
{
"type": "record",
"name": "DebugAggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "Unnoised metric associated with the bucket."
},
{
"name": "noise",
"type": "long",
"doc": "The noise applied to the metric in the regular result."
}
{
"name":"annotations",
"type": {
"type": "array",
"items": {
"type":"enum",
"name":"bucket_tags",
"symbols":["in_domain","in_reports"]
}
}
]
}
変換すると、概要レポートは例 results.json
のようになります。debug_run が有効になっている場合、デバッグ概要レポートは例 debug_results.json
のような結果を返します。
results.json(例)
集計サービスからの AVRO レポートは、バケットキーと、バケット値のノイズが追加されたサマリー / 集計値がある場合に、似たようなものになります。
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json(例)
集計サービスからのデバッグ AVRO レポートは、unnoised_metric
(ノイズのないバケットキーの概要)と unnoised_metric
に追加されたノイズを受け取る場合は次のようになります。
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
アノテーションには in_reports
または in_domain
も含まれます。これは次のことを意味します。
in_reports
: バケットキーは集計可能レポート内で使用できます。in_domain
: バケットキーはoutput_domain
AVRO ファイル内で使用できます。