이 가이드에서는 암호화된 측정 보고서가 광고 기술 제공업체에 전송되는 방식을 설명합니다. Chrome 브라우저와 클라이언트는 이러한 보고서를 지정된 보고 엔드포인트로 전송하며, 여기서 광고 기술 플랫폼은 집계 가능한 보고서를 수신하고 저장합니다. 이러한 엔드포인트는 제공업체의 보고 출처 내 .well-known URL에 있으며 플랫폼에서 호스팅하므로 광고 기술 제공업체가 Attribution Reporting API 또는 Private Aggregation API를 사용하여 액세스할 수 있습니다.
다음 단계에서는 집계 가능한 보고서를 수신하고 저장하는 집계 서비스의 프로세스를 자세히 설명합니다.
- 트리거되면 브라우저는 교차 사이트 및 전환 데이터에 관한 세부정보가 포함된 집계 가능한 보고서를 전송합니다.
- 브라우저는 암호화된 보고서를 광고 기술 보고 도메인 내의
.well-knownURL로 전송합니다. - 시스템은 처리를 위해 보고서 배치를 집계 서비스로 전달합니다.
- 집계 서비스는 보고서를 통계적으로 요약합니다.
- 집계 서비스는 요약된 데이터에 노이즈를 추가하여 사용자 개인 정보 보호를 강화합니다.
- 시스템은 광고 기술 회사가 분석 및 측정 목적으로 보고서를 사용할 수 있도록 합니다.
다음 표에서는 Private Aggregation API 및 Attribution Reporting API의 디버그 및 실시간 엔드포인트를 설명합니다.
| API | 엔드포인트 | 설명 |
|---|---|---|
| Private Aggregation API |
|
|
| Attribution Reporting API |
|
|
보고 출처는 POST 호출을 통해 JSON 보고서를 수신합니다. 그런 다음 시스템은 이러한 보고서를 Avro 형식으로 변환하여 클라우드 스토리지에 저장합니다. 일괄 처리 후 시스템은 요약을 위해 Avro 보고서를 집계 서비스로 전송합니다.
광고 기술 플랫폼은 일괄 Avro 보고서를 처리할 준비가 되었다고 판단되면 집계 서비스에 집계 작업 요청을 트리거합니다. 광고 기술 플랫폼의 클라우드 환경 내에 호스팅되는 이 서비스는 동일한 저장소 위치에서 필요한 Avro 보고서를 가져옵니다. 보안상의 이유로 집계 서비스는 승인된 컨테이너 이미지를 사용하도록 구성되어야 합니다. 사용 가능한 컨테이너 이미지는 개인 정보 보호 샌드박스/집계 서비스 GitHub 저장소를 참고하세요.
다음은 각 API에서 반환하는 보고서의 대표적인 예시입니다.
- 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 보고서로 변환
집계 가능한 보고서는 일괄 처리를 위해 Apache Avro 데이터 직렬화 형식이어야 합니다. Avro 보고서를 만들려면 AVSC 스키마를 사용해야 합니다. AVSC 스키마 파일은 Avro 레코드 구조와 데이터 유형을 정의합니다. AVSC 스키마 예시는 이 avrodoc/schemata GitHub 저장소의 example.avsc 파일을 참고하세요.
JavaScript 코드의 예는 privacysandbox/aggregation-service GitHub 저장소에 있는 집계 가능한 보고서 수집 및 일괄 처리 페이지의 보고서 수집, 변환, 일괄 처리 섹션에서 확인할 수 있습니다.
모든 보고서를 단일 AVRO 파일에 저장하거나 여러 파일에 배포할 수 있습니다. AVRO 파일에는 크기 제한이 없지만 일반적으로 파일 수가 클라우드 인스턴스의 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 |
바이트 |
payload는 실시간 또는 프로덕션 보고서의 경우 base64로 디코딩되고 바이트 배열로 변환되어야 합니다.
|
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로 변환된 JSON 보고서)와 연결된 도메인 파일이 필요합니다. 시스템은 집계 가능한 보고서에서 사전 선언된 키를 추출하여 출력 도메인의 요약 보고서에 포함합니다. 이러한 중요한 집계 키에 관한 자세한 내용은 기여 분석 보고용 집계 키 이해하기 및 비공개 집계 API 기본사항의 집계 키 섹션을 참고하세요. 출력 도메인에는 버킷 키 값을 나타내는 bucket 필드도 포함됩니다.
도메인 파일은 다음 스키마를 사용하는 Avro 형식이어야 합니다.
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
}
]
}
버킷 키
출력 도메인 내의 버킷 키는 16진수 바이트 문자열로 표현되어야 합니다.
예를 들면 다음과 같습니다.
버킷 키가 소수점 값 1369인 경우:
1369를 16진수 등가값인 559로 변환
16진수 문자열 '559'를 바이트 문자열로 변환합니다.
그런 다음 버킷 키의 이 바이트 문자열 표현을 출력 도메인 Avro 스키마에 포함해야 합니다.
중요 고려사항:
데이터 유형: Avro 스키마 내의 버킷 키는 16진수 바이트 문자열 표현을 수용하도록 바이트 유형으로 정의되어야 합니다.
변환: 십진수에서 16진수로, 다시 바이트 문자열로 변환하는 작업은 Python 또는 Java를 사용하여 구현할 수 있습니다.
이 접근 방식을 사용하면 버킷 키의 형식이 올바르고 출력 도메인의 Avro 스키마 내에서 예상되는 데이터 유형과 호환됩니다.
일괄 보고서
개인 정보 보호 예산 및 일괄 처리 전략에 관한 자세한 내용은 일괄 처리 전략 문서를 참고하세요. 집계 가능한 보고서의 경우 scheduled_report_time와 일괄 실행 날짜 사이에 MAX_REPORT_AGE 제한 (현재 90일)이 적용됩니다.
요약 보고서
일괄 처리 후 집계 서비스는 results.avsc 스키마를 사용하여 Avro 형식의 요약 보고서를 만듭니다.
작업이 완료되면 요약 보고서가 createJob 요청에 명시된 대로 output_data_bucket_name 버킷 내 output_data_blob_prefix에 저장됩니다.
debug_run가 사용 설정된 집계 서비스 배치의 경우 요약 보고서와 디버그 요약 보고서라는 두 가지 보고서가 생성됩니다. 디버그 요약 보고서는 output_data_blob_prefix/debug 폴더에 있습니다. 디버그 요약 보고서는 debug_results.avsc 스키마를 사용합니다.
요약 보고서와 디버그 보고서 모두 이름이 [output_data_blob_prefix]-1-of-1.avro입니다. output_data_blob_prefix가 summary/summary.avro인 경우 보고서는 summary-1-of-1.avro라는 이름으로 요약 폴더에 있습니다.
results.avsc 예시
다음은 results.avsc의 Avro 스키마 예입니다.
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
},
{
"name": "metric",
"type": "long",
"doc": "The metric associated with the bucket"
}
]
}
이 Avro 스키마 예에서는 AggregatedFact라는 레코드를 정의합니다.
debug_results.avsc 예시
다음은 debug_results.avsc의 Avro 스키마 예입니다.
{
"type": "record",
"name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "The raw metric for 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 예와 유사합니다.
Avro 보고서 형식
집계 서비스에서 수신하는 Avro 보고서는 일반적으로 일관된 형식을 따릅니다. Avro 보고서 형식에는 다음 필드가 포함됩니다.
bucket: 데이터 집계의 고유 식별자입니다 (예: \u0005Y).
metric: 해당 버킷의 집계된 값입니다. 이 값에는 개인 정보 보호를 위해 추가된 노이즈가 포함되는 경우가 많습니다.
예를 들면 다음과 같습니다.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json 예시
집계 서비스의 디버그 Avro 보고서는 다음 debug_results.json 예와 유사합니다. 이러한 보고서에는 버킷 키, unnoised_metric (노이즈 적용 전 버킷 키의 요약), 해당 측정항목에 추가된 노이즈가 포함됩니다.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
주석에는 다음 값도 포함됩니다.
in_reports: 집계 가능한 보고서 내에서 사용할 수 있는 버킷 키입니다.in_domain:output_domainAvro 파일 내에서 사용할 수 있는 버킷 키입니다.