Otrzymywanie raportów zbiorczych do sklepu

Gdy technologie reklamowe aktywują interfejsy API do pomiarów (Attribution Reporting API lub Private Aggregation API), zaszyfrowane raporty są wysyłane z przeglądarki Chrome lub klienta do punktu końcowego raportowania danej technologii reklamowej, którym jest adres URL .well-known z pochodzącym z niej raportem. Punkt końcowy raportowania jest hostowany przez dostawcę technologii reklamowej, aby zbierać zaszyfrowane raporty.

Diagram raportu AgS
Diagram raportu AgS

Oto punkty końcowe poszczególnych interfejsów API:

  • Agregacja prywatna

    • Debugowanie [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • Na żywo [reporting-origin]/.well-known/private-aggregation/report-shared-storage lub /.well-known/private-aggregation/report-protected-audience

  • Attribution Reporting

    • Debugowanie [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • Na żywo [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Technicyczni otrzymają raporty w formacie JSON za pomocą wywołania POST. Specjaliści ds. technologii reklamowych będą zbierać te raporty w formacie JSON, a potem konwertować je do formatu AVRO, który jest używany w usłudze agregacji. Po przekonwertowaniu raporty AVRO są przechowywane w chmurze dostawcy technologii reklamowej na potrzeby późniejszego zbiorczego przetwarzania.

Gdy dostawca technologii reklamowych będzie gotowy do zbiorczego przetwarzania danych, wyśle żądanie wykonania zadania agregacji za pomocą usługi do agregacji, w której raporty są pobierane z magazynu danych w chmurze dostawcy. Usługa do agregacji jest hostowana w chmurze dostawcy technologii reklamowych i powinna mieć dozwolony obraz.

Otrzymane zgłoszenia wyglądają mniej więcej tak:

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

Konwertowanie danych w formacie JSON na raporty AVRO

W przypadku zbiorczego przetwarzania raporty podlegające agregacji muszą być w formacie AVRO. Aby utworzyć raport AVRO, musisz mieć schemat AVRO (AVSC) raportu.

Przykładowy kod JavaScript jest dostępny w repozytorium GitHub usługi agregacji.

Poniżej znajduje się schemat AVRO dla raportów zbiorczych. Różne pola w raportach to payload, key_id i shared_info.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
Parametr Typ Opis
payload Bajty Dane payload muszą zostać zdekodowane z formatu base64 i przekształcone w tablicę bajtów z payload na potrzeby raportów na żywo lub produkcyjnych.
debug_cleartext_payload Bajty Dane ładunku muszą zostać zdekodowane z formatu Base64 i przekształcone na tablicę bajtów z poziomu debug_cleartext_payload na potrzeby raportów debugowania.
key_id Ciąg znaków Będzie to ciąg znaków key_id znaleziony w raporcie. key_id będzie 128-bitowym identyfikatorem uniwersalnym podobnym do UUID.
shared_info Ciąg znaków Będzie to nienaruszony ciąg znaków znaleziony w polu shared_info raportu.

Oto przykładowy plik JSON raportu:

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

Domena wyjściowa AVRO

Aby generować raporty podsumowujące za pomocą usługi do agregacji, usługa adtech wymaga raportów podlegających agregacji i pliku domeny. Raporty podlegające agregacji to raporty w formacie JSON otrzymane w źródle raportowania i przekształcone do formatu AVRO. Domeny wyjściowe będą zawierać wstępnie zadeklarowane klucze, które zostaną zebrane z raportów podlegających agregacji i zapisane w raportach podsumowań. Dowiedz się więcej o tych kluczach w raportach atrybucji i kluczach w Private Aggregation. Domena wyjściowa będzie zawierać pole zbiorcze, a wartość zbiorczego pola będzie odpowiadać kluczowi zbiorczego pola.

Plik domeny musi też być w formacie AVRO z użyciem tego schematu:

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

Klucz zasobnika

Klucz puli powinien być szesnastkowym ciągiem bajtów klucza puli. Przykładem może być klucz 1369 w systemie dziesiętnym. Po przekonwertowaniu na format szesnastkowy będzie to 559. Następnie musisz przekonwertować wartość 559 na ciąg bajtów, który zostanie dodany do domeny wyjściowej AVRO.

Schemat klucza zasobnika AgS
Diagram klucza zbioru AgS.

Raporty zbiorcze

Więcej informacji o budżetach na potrzeby prywatności i zbiorach danych znajdziesz w artykule Strategie zbiorczego przetwarzania danych. Pamiętaj też, że raport, który można agregować, można przetwarzać zbiorczo tylko w określonym czasie. Raport nie może przekraczać wartości MAX_REPORT_AGE w okresie od scheduled_report_time do daty uruchomienia partii (obecnie 90 dni).

Raporty zbiorcze

Po zgrupowaniu danych usługa do agregacji tworzy raport podsumowujący w formacie AVRO. Raport podsumowujący używa schematu results.avsc.

Raport podsumowujący będzie dostępny w grupie output_data_blob_prefix w worku output_data_bucket_name określonym w żądaniu createJob.

W przypadku partii usługi do agregacji, w których włączono debug_run, tworzy 2 raporty. Raport podsumowujący i raport podsumowujący debugowania. Raport z debugowaniem znajdziesz w folderze output_data_blob_prefix/debug.

Wygenerowany raport debugowania używa schematu debug_results.avsc.

Zarówno raport z podsumowaniem, jak i raport debugowania będą miały nazwę [output_data_blob_prefix]-1-of-1.avro. Jeśli parametr output_data_blob_prefix ma wartość summary/summary.avro, raport znajdziesz w folderze summary o nazwie 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"]
          }
       }
    ]
  }

Po przekonwertowaniu raport podsumowania będzie wyglądał tak jak przykład results.json. Gdy debug_run jest włączony, raport podsumowania debugowania zwraca dane podobne do przykładu debug_results.json.

results.json (przykład)

Raporty AVRO pochodzące z usługi do agregacji mogą wyglądać podobnie, gdy masz klucz zbioru i wartość podsumowania lub agregacji z dodanym szumem wartości zbioru.

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

debug_results.json (przykład)

Raporty debugowania AVRO pochodzące z usługi do agregacji powinny wyglądać podobnie do tego, w którym otrzymujesz klucze zbiorów, unnoised_metric (podsumowanie kluczy zbiorów bez szumu) i szum dodawany do unnoised_metric.

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

Oprócz tego adnotacje będą zawierać in_reports lub in_domain, co oznacza:

  • in_reports: klucz zbiornika jest dostępny w raportach zbiorczych
  • in_domain: klucz zasobnika jest dostępny w pliku output_domain AVRO