집계 가능한 보고서 수신 및 저장

광고 기술이 측정 API (Attribution Reporting API 또는 Private Aggregation API)를 트리거하면 암호화된 보고서가 Chrome 브라우저 / 클라이언트 측에서 광고 기술의 보고 출처가 있는 .well-known URL인 광고 기술의 보고 엔드포인트로 전송됩니다. 보고 엔드포인트는 광고 기술에서 호스팅하여 암호화된 보고서를 수집합니다.

AgS 보고서 다이어그램
AgS 보고서 다이어그램.

API별 엔드포인트는 다음과 같습니다.

  • Private Aggregation

    • [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 코드는 집계 서비스 GitHub 저장소에서 확인할 수 있습니다.

다음은 집계 가능한 보고서의 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 보고서입니다. 출력 도메인에는 집계 가능한 보고서에서 수집되어 요약 보고서에 작성될 사전 선언된 키가 포함됩니다. Attribution Reporting의 키 및 Private Aggregation의 키에 대해 자세히 알아보세요. 출력 도메인에는 필드 버킷이 포함되고 버킷 값은 버킷 키가 됩니다.

도메인 파일도 다음 스키마를 사용하여 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진수) 키가 있습니다. 1369를 16진수로 변환하면 559가 됩니다. 그런 다음 559를 바이트 문자열로 변환하여 출력 도메인 AVRO에 추가해야 합니다.

AgS 버킷 키 다이어그램
AgS 버킷 키 다이어그램.

일괄 보고서

개인 정보 보호 예산 및 일괄 처리에 대해 자세히 알아보려면 일괄 처리 전략 문서를 참고하세요. 또한 집계 가능한 보고서는 특정 기간 내에만 일괄 처리할 수 있습니다. 보고서는 scheduled_report_time와 배치 실행 날짜 사이의 기간 (현재 90일)이 MAX_REPORT_AGE를 초과해서는 안 됩니다.

요약 보고서

일괄 처리 후 집계 서비스는 AVRO 형식으로 요약 보고서를 생성합니다. 요약 보고서는 results.avsc 스키마를 사용합니다.

요약 보고서는 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 폴더에 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 파일 내에서 사용할 수 있습니다.