Ricevere e archiviare report aggregabili

Quando le ad tech attivano le API di misurazione (API Attribution Reporting o API Private Aggregation), i report criptati vengono inviati dal lato client / browser di Chrome all'endpoint di reporting dell'ad tech, che è un URL .well-known con l'origine dei report dell'ad tech. L'endpoint di generazione di report è ospitato dalla tecnologia pubblicitaria per raccogliere i report criptati.

Diagramma del report AgS.

Di seguito sono riportati gli endpoint per API:

  • Private Aggregation

    • Debug [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • In diretta su [reporting-origin]/.well-known/private-aggregation/report-shared-storage o /.well-known/private-aggregation/report-protected-audience
  • Report sull'attribuzione

    • Debug [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • In diretta [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Gli esperti di tecnologia pubblicitaria riceveranno i report in formato JSON tramite una chiamata POST. Gli esperti di tecnologia pubblicitaria raccoglieranno questi report JSON e li convertiranno in formato AVRO, utilizzato nel servizio di aggregazione. Una volta convertiti, i report AVRO vengono archiviati nello spazio di archiviazione sul cloud dell'ad tech per l'aggregazione successiva.

Una volta che la tecnologia pubblicitaria è pronta per l'aggregazione, attiverà una richiesta di job di aggregazione tramite il servizio di aggregazione, in cui i report vengono recuperati dallo spazio di archiviazione sul cloud della tecnologia pubblicitaria. Il servizio di aggregazione è ospitato nell'archiviazione sul cloud della tecnologia pubblicitaria e deve avere un'immagine inserita nella lista consentita.

Le segnalazioni ricevute hanno il seguente aspetto:

API Private Aggregation

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

API Attribution Reporting

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

Convertire i report JSON in AVRO

Quando vengono raggruppati, i report aggregabili devono essere in formato AVRO. Per creare un report AVRO, devi disporre dello schema AVRO (AVSC) del report.

Un codice JavaScript di esempio è disponibile nel repository GitHub del servizio di aggregazione.

Di seguito è riportato lo schema AVRO per i report aggregabili. I diversi campi per i report sono payload, key_id e shared_info.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
Parametro Tipo Descrizione
payload Byte Il payload dovrà essere decodificato in base64 e convertito in un array di byte da payload per i report dal vivo / di produzione.
debug_cleartext_payload Byte Il payload dovrà essere decodificato in base64 e convertito in un array di byte da debug_cleartext_payload per i report di debug.
key_id Stringa Si tratta della stringa key_id trovata nel report. key_id sarà un identificatore univoco universale a 128 bit simile.
shared_info Stringa Si tratta della stringa non alterata trovata nel campo shared_info del report.

Ecco un esempio di report 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\"}"
}

Dominio di output AVRO

Per generare report di riepilogo utilizzando il servizio di aggregazione, la tecnologia pubblicitaria richiede i report aggregabili e il file del dominio. I report aggregabili saranno i report JSON ricevuti nell'origine report e convertiti in formato AVRO. I domini di output conterranno le chiavi predefinite che verranno raccolte dai report aggregabili e scritte nei report di riepilogo. Scopri di più su queste chiavi nei report sull'attribuzione e sulle chiavi nell'aggregazione privata. Il dominio di output conterrà il bucket del campo e il valore del bucket sarà la chiave del bucket.

Il file del dominio dovrà inoltre essere in formato AVRO utilizzando lo schema seguente:

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

Chiave del bucket

La chiave del bucket deve essere una stringa di byte esadecimale della chiave del bucket. Un esempio è avere una chiave pari a 1369 in decimale. Se viene convertito in esadecimale, sarà 559. Poi dovrai convertire 559 in una stringa di byte da aggiungere al dominio di output AVRO

Diagramma delle chiavi del bucket AgS.

Report batch

Per saperne di più sui budget per la privacy e sul raggruppamento, consulta la documentazione sulle strategie di raggruppamento. Inoltre, tieni presente che un report aggregabile può essere raggruppato solo entro un determinato periodo di tempo. Un report non deve superare il valore MAX_REPORT_AGE tra il giorno scheduled_report_time e la data di esecuzione del batch (attualmente 90 giorni).

Report di riepilogo

Dopo l'aggregazione, il servizio di aggregazione crea il report di riepilogo in formato AVRO. Il report di riepilogo utilizza lo schema results.avsc.

Il report di riepilogo si trova in output_data_blob_prefix nel bucket output_data_bucket_name indicato nella richiesta createJob.

Per i batch del servizio di aggregazione in cui è attivata la funzionalità debug_run, vengono creati due report. Il report di riepilogo e il report di riepilogo del debug. Il report di riepilogo del debug si trova nella cartella output_data_blob_prefix/debug.

Il report di debug generato utilizza lo schema debug_results.avsc.

Sia il report di riepilogo che quello di debug verranno denominati [output_data_blob_prefix]-1-of-1.avro. Se il prefisso output_data_blob è summary/summary.avro, il report si troverà nella cartella di riepilogo con il nome 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"]
          }
       }
    ]
  }

Una volta convertito, il report di riepilogo avrà il seguente aspetto results.json. Quando debug_run è attivato, il report di riepilogo del debug restituisce un valore simile all'esempio debug_results.json.

results.json (esempio)

I report AVRO provenienti dal servizio di aggregazione possono avere un aspetto simile se hai la chiave del bucket e il valore di riepilogo / aggregazione con il rumore aggiunto dei valori del bucket.

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

debug_results.json (esempio)

I report di debug AVRO provenienti dal servizio di aggregazione dovrebbero essere simili al seguente, dove ricevi le chiavi del bucket, unnoised_metric (riepilogo delle chiavi del bucket senza rumore) e il rumore aggiunto a unnoised_metric.

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

Le annotazioni conterranno anche in_reports e / o in_domain, che significano:

  • in_reports: la chiave del bucket è disponibile nei report aggregabili
  • in_domain: la chiave del bucket è disponibile all'interno del file AVRO output_domain