Wenn AdTechs Mess-APIs (Attribution Reporting API oder Private Aggregation API) auslösen, werden die verschlüsselten Berichte vom Chrome-Browser / von der Clientseite an den Berichts-Endpunkt des AdTech gesendet. Das ist eine .well-known-URL mit dem Berichtsursprung des AdTech. Der Berichtsendpunkt wird von AdTech gehostet, um die verschlüsselten Berichte zu erfassen.
Im Folgenden finden Sie die Endpunkte für die einzelnen APIs:
Private Aggregation
- Debug
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - Live-
[reporting-origin]/.well-known/private-aggregation/report-shared-storageoder/.well-known/private-aggregation/report-protected-audience
- Debug
Attributionsberichte
- Debug
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - Aktuell
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Debug
Ad-Tech-Unternehmen erhalten die Berichte im JSON-Format über einen POST-Aufruf. Ad-Tech-Unternehmen erfassen diese JSON-Berichte und konvertieren sie später in das AVRO-Format, das im Aggregation Service verwendet wird. Nach der Konvertierung werden die AVRO-Berichte im Cloud-Speicher des Ad-Tech-Unternehmens gespeichert, um später in Batches verarbeitet zu werden.
Sobald die AdTech-Lösung für das Batching bereit ist, löst sie über den Aggregationsdienst eine Anfrage für einen Aggregationsjob aus. Die Berichte werden dann aus dem Cloud-Speicher der AdTech-Lösung abgerufen. Der Aggregation Service wird im Cloud-Speicher des Ad-Tech-Unternehmens gehostet und sollte ein auf der Zulassungsliste stehendes Image haben.
Die eingegangenen Meldungen sehen in etwa so aus:
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 in AVRO-Berichte konvertieren
Bei der Batchverarbeitung müssen aggregierbare Berichte im AVRO-Format vorliegen. Zum Erstellen eines AVRO-Berichts benötigen Sie das AVRO-Schema (AVSC) für den Bericht.
Ein Beispiel für JavaScript-Code ist im GitHub-Repository des Aggregation Service verfügbar.
Im Folgenden finden Sie das AVRO-Schema für aggregierbare Berichte. Die verschiedenen Felder für die Berichte sind payload, key_id und shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Parameter | Typ | Beschreibung |
|---|---|---|
payload |
Byte |
Die Nutzlast muss für Live- und Produktionsberichte base64-decodiert und in ein Byte-Array aus payload konvertiert werden.
|
debug_cleartext_payload |
Byte |
Die Nutzlast muss für Debugberichte aus debug_cleartext_payload base64-decodiert und in ein Byte-Array konvertiert werden.
|
key_id |
String | Das ist der key_id-String aus dem Bericht. Die key_id ist eine 128‑Bit-Universally Unique Identifier (UUID). |
shared_info |
String | Dies ist der unverfälschte String, der im Feld „shared_info“ des Berichts enthalten ist. |
Hier ist ein Beispiel für einen JSON-Bericht:
{
"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-Ausgabedomain
Damit Zusammenfassungsberichte mit dem Aggregationsdienst generiert werden können, benötigt die Ad-Tech-Plattform die aggregierbaren Berichte und die Domänendatei. Die aggregierbaren Berichte sind die JSON-Berichte, die am Berichterstellungsursprung empfangen und in das AVRO-Format konvertiert werden. Ausgabedomänen enthalten die vorab deklarierten Schlüssel, die aus Ihren aggregierbaren Berichten erfasst und in die Zusammenfassungsberichte geschrieben werden. Weitere Informationen zu Schlüsseln im Attributionsberichterstattungs-API und Schlüsseln in der privaten Aggregation Die Ausgabedomäne enthält das Feld „bucket“ und der Bucket-Wert ist Ihr Bucket-Schlüssel.
Die Domänendatei muss auch im AVRO-Format mit dem folgenden Schema vorliegen:
{
"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."
}
]
}
Bucket-Schlüssel
Der Bucket-Schlüssel sollte ein Hex-Bytestring des Bucket-Schlüssels sein. Ein Beispiel dafür ist der Dezimalschlüssel 1369. In Hexadezimal umgerechnet ist das 559. Anschließend müssen Sie 559 in einen Bytestring konvertieren, der dem AVRO der Ausgabedomäne hinzugefügt werden soll.
Batch-Berichte
Weitere Informationen zu Privacy Budgets und Batching finden Sie in der Dokumentation zu Batching-Strategien. Außerdem ist zu beachten, dass ein aggregierbarer Bericht nur innerhalb eines bestimmten Zeitraums gebatcht werden kann. Ein Bericht sollte das MAX_REPORT_AGE zwischen dem scheduled_report_time und dem Batch-Ausführungsdatum (derzeit 90 Tage) nicht überschreiten.
Zusammenfassende Berichte
Nach dem Batching erstellt der Aggregationsdienst den Zusammenfassungsbericht im AVRO-Format. Im Übersichtsbericht wird das results.avsc-Schema verwendet.
Der zusammenfassende Bericht befindet sich im output_data_blob_prefix im Bucket output_data_bucket_name, der in der createJob-Anfrage angegeben ist.
Für Aggregationsdienst-Batches, bei denen „debug_run“ aktiviert ist, werden zwei Berichte erstellt. Der Zusammenfassungsbericht und der Debug-Zusammenfassungsbericht. Der Debug-Zusammenfassungsbericht befindet sich im Ordner output_data_blob_prefix/debug.
Für den generierten Debug-Bericht wird das debug_results.avsc-Schema verwendet.
Sowohl die Zusammenfassung als auch der Debug-Bericht werden als [output_data_blob_prefix]-1-of-1.avro bezeichnet. Wenn Ihr „output_data_blob_prefix“ summary/summary.avro ist, befindet sich der Bericht im Ordner „summary“ mit dem Namen 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"]
}
}
]
}
Nach der Umstellung sieht Ihr Übersichtsbericht wie im Beispiel results.json aus. Wenn „debug_run“ aktiviert ist, wird im Debug-Zusammenfassungsbericht etwas Ähnliches wie im Beispiel debug_results.json zurückgegeben.
results.json (Beispiel)
AVRO-Berichte aus dem Aggregationsdienst können ähnlich aussehen, da sie den Bucket-Schlüssel und den Zusammenfassungs- bzw. aggregierten Wert mit zusätzlichem Rauschen der Bucket-Werte enthalten.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (Beispiel)
AVRO-Berichte, die vom Aggregationsdienst stammen, sollten in etwa so aussehen: Sie erhalten Ihre Bucket-Schlüssel, unnoised_metric (Zusammenfassung der Bucket-Schlüssel ohne Rauschen) und das Rauschen, das unnoised_metric hinzugefügt wird.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Die Annotationen enthalten auch in_reports und / oder in_domain. Das bedeutet:
in_reports: Der Bucket-Schlüssel ist in den aggregierbaren Berichten verfügbar.in_domain: Der Bucket-Schlüssel ist in der AVRO-Dateioutput_domainverfügbar.