Menerima & Simpan Laporan Agregat

Saat teknologi iklan memicu API pengukuran (Attribution Reporting API atau Private Aggregation API), laporan terenkripsi dikirim dari browser Chrome/sisi klien ke endpoint pelaporan teknologi iklan yang merupakan URL .well-known dengan asal pelaporan teknologi iklan. Endpoint pelaporan dihosting oleh teknologi iklan untuk mengumpulkan laporan terenkripsi.

Diagram Laporan AgS

Berikut adalah endpoint per API:

  • Agregasi Pribadi

    • Men-debug [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • [reporting-origin]/.well-known/private-aggregation/report-shared-storage atau /.well-known/private-aggregation/report-protected-audience aktif

  • Pelaporan Atribusi

    • Men-debug [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • Live [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Teknologi iklan akan menerima laporan dalam format JSON melalui panggilan POST. Teknologi iklan akan mengumpulkan laporan JSON ini, lalu mengonversinya menjadi format AVRO yang digunakan di Layanan Agregasi. Setelah dikonversi, laporan AVRO disimpan di penyimpanan cloud teknologi iklan untuk pengelompokan nanti.

Setelah teknologi iklan siap untuk dikelompokkan, teknologi iklan akan memicu permintaan tugas agregasi melalui layanan agregasi tempat laporan diambil dari penyimpanan cloud teknologi iklan. Layanan Agregasi dihosting di penyimpanan cloud teknologi iklan dan harus memiliki gambar yang diizinkan.

Laporan yang diterima terlihat mirip dengan yang berikut ini:

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"
  }

Mengonversi laporan JSON ke AVRO

Saat mengelompokkan, laporan agregat harus dalam format AVRO. Untuk membuat laporan AVRO, Anda memerlukan skema AVRO laporan (AVSC).

Contoh kode JavaScript tersedia di repositori GitHub Layanan Agregasi.

Anda dapat memiliki 1 file AVRO untuk semua laporan atau membagi laporan menjadi beberapa file AVRO. Tidak ada batasan ukuran AVRO. Untuk alasan performa, sebaiknya pertahankan jumlah file AVRO dalam jumlah antara jumlah CPU yang tersedia untuk instance Cloud Anda hingga 1.000.

Berikut adalah Skema AVRO untuk laporan Gabungan. Kolom yang berbeda untuk laporan adalah payload, key_id, dan shared_info.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
Parameter Jenis Deskripsi
payload Byte Payload harus didekode dalam base64 dan dikonversi ke array byte dari payload untuk laporan live / produksi.
debug_cleartext_payload Byte Payload harus didekode base64 dan dikonversi menjadi array byte dari debug_cleartext_payload untuk laporan debug.
key_id String Ini akan menjadi string key_id yang ditemukan dalam laporan. key_id akan berupa ID unik universal 128-bit yang serupa.
shared_info String Ini akan berupa string yang tidak dimodifikasi yang ditemukan di kolom laporan shared_info.

Berikut adalah contoh JSON laporan:

{ 
   "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\"}"
}

Domain Output AVRO

Untuk membuat laporan ringkasan menggunakan Layanan Agregasi, teknologi iklan memerlukan laporan agregat dan file domain. Laporan agregat akan berupa laporan JSON yang diterima dalam asal pelaporan dan dikonversi ke format AVRO. Domain output akan berisi kunci yang telah dideklarasikan sebelumnya yang akan dikumpulkan dari laporan agregat Anda dan akan ditulis ke dalam laporan ringkasan. Pelajari lebih lanjut kunci di Pelaporan Atribusi dan kunci dalam Agregasi Pribadi. Domain output akan berisi bucket kolom dan nilai bucket akan menjadi kunci bucket Anda.

File domain juga harus dalam format AVRO menggunakan skema berikut:

  {
    "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."
      }
    ]
  }

Kunci Bucket

Kunci bucket harus berupa string byte heksa dari kunci bucket. Contohnya adalah memiliki kunci 1369 dalam Desimal. Jika dikonversi ke Hex, nilainya akan menjadi 559. Maka, Anda harus mengonversi 559 menjadi bytestring untuk ditambahkan ke domain output AVRO

Diagram Kunci Bucket AgS

Laporan batch

Untuk lebih memahami anggaran privasi dan pengelompokan, buka dokumen strategi pengelompokan. Selain itu, perlu diingat bahwa laporan gabungan hanya dapat dikelompokkan dalam jangka waktu tertentu. Laporan tidak boleh melebihi MAX_REPORT_AGE antara scheduled_report_time dan tanggal operasi batch (saat ini 90 hari).

Laporan Ringkasan

Setelah pengelompokan, Aggregation Service akan membuat laporan ringkasan dalam format AVRO. Laporan ringkasan menggunakan skema results.avsc.

Laporan ringkasan akan berada di output_data_blob_prefix dalam bucket output_data_bucket_name yang dinyatakan dalam permintaan createJob.

Untuk batch Layanan Agregasi yang mengaktifkan debug_run, kode ini akan membuat dua laporan. Laporan ringkasan dan laporan ringkasan debug. Laporan ringkasan debug akan berada di folder output_data_blob_prefix/debug.

Laporan debug yang dibuat menggunakan skema debug_results.avsc.

Laporan ringkasan dan debug akan diberi nama [output_data_blob_prefix]-1-of-1.avro. Jika output_data_blob_prefix Anda adalah summary/summary.avro, laporan akan berada di folder ringkasan dengan nama 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"]
          }
       }
    ]
  }

Setelah dikonversi, laporan ringkasan Anda akan terlihat seperti contoh results.json. Jika debug_run diaktifkan, laporan ringkasan debug akan menampilkan sesuatu yang mirip dengan contoh debug_results.json.

results.json (contoh)

Laporan AVRO yang berasal dari Layanan Agregasi dapat terlihat mirip jika Anda memiliki kunci bucket dan nilai gabungan / ringkasan dengan derau tambahan pada nilai bucket.

  {
    "bucket": "\u0005Y",
    "metric": 26308
  }

debug_results.json (contoh)

Laporan AVRO debug yang berasal dari Layanan Agregasi akan terlihat mirip dengan yang berikut ini, tempat Anda menerima kunci bucket, unnoised_metric (ringkasan kunci bucket tanpa derau), dan derau yang ditambahkan ke unnoised_metric.

  {
    "bucket": "\u0005Y",
    "unnoised_metric": 128,
    "noise": -17948,
    "annotations": [
      "in_reports",
      "in_domain"
    ]
  }

Anotasi juga akan berisi in_reports dan / atau in_domain yang berarti:

  • in_reports: kunci bucket tersedia di dalam laporan gabungan
  • in_domain: kunci bucket tersedia di dalam file AVRO output_domain