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

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

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)가 필요합니다.

샘플 자바스크립트 코드는 집계 서비스 GitHub 저장소에서 제공됩니다.

모든 보고서에 하나의 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진수 바이트 문자열이어야 합니다. Decimal에서 키가 1369인 경우를 예로 들 수 있습니다. 10진수로 변환하면 559가 됩니다. 그런 다음 559를 출력 도메인 AVRO에 추가할 바이트 문자열로 변환해야 합니다.

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-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 파일 내에서 사용할 수 있습니다.