Erstellen von Attributionsberichten
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.
Dieser Artikel erklärt, wie Berichte der Attribution Reporting API generiert werden - sowohl Attributionsberichte als auch Debug-Berichte - und wie Sie die generierten Berichte steuern können. Dazu gehört das Umgang mit Rauschen, die Priorisierung von Berichten, das Filtern von Berichten und das Generieren von Debug-Berichten.
Grundlegender Prozess
Wenn eine Übereinstimmung zwischen einem Auslöser und einer Quelle auftritt, generiert der Browser einen Bericht und sendet ihn über eine unbeglaubigte POST
-Anfrage an einen bestimmten Endpunkt im Reporting-Ursprung:
- Für Event-Level-Berichte ist dies
<reporting-origin>/.well-known/attribution-reporting/report-event-attribution
. - Für zusammenfassende Berichte ist dies
<reporting-origin>/.well-known/attribution-reporting/report-aggregate-attribution
.
Der <reporting-origin>
ist gleich dem, der die Quelle und den Auslöser registriert hat.
Die Berichtsdaten sind in einer JSON-Struktur enthalten.
Event-Level-Berichte
Event-Level-Berichte werden erstellt und zur Versendung am Ende ihres Berichtsfensters geplant. Die Länge des Berichtsfensters wird durch die Werte in den Feldern "event_report_window"
oder "event_report_windows"
im Header Attribution-Reporting-Register-Source
der Quelle bestimmt.
Wenn keiner dieser Felder angegeben ist, wird das Berichtsfenster auf die folgenden Standardwerte zurückgesetzt:
- Für ereignisbasierte Quellen endet das Standardberichtsfenster mit dem Ablauf der Quelle, der im
Attribution-Reporting-Register-Source
-Feld"expiry"
festgelegt ist. Diese beträgt standardmäßig 30 Tage nach der Registrierung, falls nicht ausdrücklich festgelegt. - Für navigationsbasierte Quellen betragen die Standardberichtsfenster 2 Tage, 7 Tage und der Ablauf der Quelle.
Siehe Benutzerdefinierte Berichtsfenster für weitere Details.
Sobald ein Event-Level-Bericht an den entsprechenden Endpunkt empfangen wird, liegt es vollständig in der Hand des Entwicklers, wie die Daten verarbeitet, gespeichert und angezeigt werden. Ein typischer Event-Level-Bericht könnte folgendermaßen aussehen:
{
"attribution_destination": "https://advertiser.example",
"source_event_id": "412444888111012",
"trigger_data": "4",
"report_id": "123e4567-e89b-12d3-a456-426614174000",
"source_type": "navigation",
"randomized_trigger_rate": 0.34,
"scheduled_report_time": "1692255696",
"source_debug_key": 647775351539539,
"trigger_debug_key": 647776891539539
}
Die Eigenschaften sind wie folgt:
"attribution_destination"
-
Ein String oder ein Array von 2–3 Strings, je nachdem, ob die Quelle mit mehreren Zielen registriert wurde oder nicht. Diese Strings repräsentieren die Attributions-
"destination"
-Seiten, die in der Quellregistrierung über den zugehörigenAttribution-Reporting-Register-Source
Response-Header festgelegt wurden. "source_event_id"
-
Ein String, der die Attribution-Quell-ID darstellt. Dies entspricht der
"source_event_id"
, die in der Quellregistrierung festgelegt wurde (über den zugehörigenAttribution-Reporting-Register-Source
Response-Header). "trigger_data"
-
Ein String, der Daten darstellt, die vom Attribution-Auslöser stammen, festgelegt in der Auslöserregistrierung (die
"trigger_data"
, festgelegt über den zugehörigenAttribution-Reporting-Register-Trigger
Response-Header). "report_id"
-
Ein String, der eine Universally Unique Identifier (UUID) für diesen Bericht darstellt, der zur Verhinderung von doppeltem Zählen verwendet werden kann.
"source_type"
-
Ein String, der entweder
"navigation"
oder"event"
entspricht, was jeweils darauf hinweist, ob die zugehörige Attribution-Quelle navigationsbasiert oder ereignisbasiert ist. "randomized_trigger_rate"
-
Eine Zufallszahl zwischen 0 und 1, die angibt, wie oft Rauschen für diese spezielle Quellkonfiguration angewendet wird.
"scheduled_report_time"
-
Ein String, der die Anzahl der Sekunden seit der Unix-Epoche darstellt, bis der Browser ursprünglich geplant hatte, den Bericht zu senden (um Ungenauigkeiten infolge von Offline-Geräten zu vermeiden, die verspätet berichten).
"source_debug_key"
Optional-
Ein 64-Bit-unsigned-Integer, der den Debugging-Schlüssel für die Attribution-Quelle darstellt. Dieser spiegelt den Wert wider, der im zugehörigen
Attribution-Reporting-Register-Source
Header's"debug_key"
-Feld festgelegt ist. Siehe Debug-Berichte für weitere Informationen. "trigger_debug_key"
Optional-
Ein 64-Bit-unsigned-Integer, der den Debugging-Schlüssel für den Attribution-Auslöser darstellt. Dieser spiegelt den Wert wider, der im zugehörigen
Attribution-Reporting-Register-Trigger
Header's"debug_key"
Feld festgelegt ist. Siehe Debug-Berichte für weitere Informationen.
Zusammenfassende Berichte
Ein zusammenfassender Bericht wird aus mehreren aggregierbaren Berichten erstellt, die am entsprechenden Endpunkt empfangen werden, und dann gebündelt, um sie für die Verarbeitung durch einen Aggregationsdienst vorzubereiten. Sobald dies geschehen ist, liegt es vollständig in der Hand des Entwicklers, wie die Daten verarbeitet, gespeichert und angezeigt werden.
Ein aggregierbarer Bericht wird standardmäßig nach dem Interagieren mit einem Auslöser generiert und geplant, mit einer zufälligen Verzögerung, um die Timings zu verwischen und die Privatsphäre zu verbessern. Für eine gegebene registrierte Attribution-Quelle werden Attributionsquellenereignisse von der Registrierung bis zum Ablauf der Quelle erfasst - dies wird als Berichtsfenster bezeichnet.
Die Ablaufzeit wird durch den expiry
-Wert im zugehörigen Attribution-Reporting-Register-Source
Header definiert, die standardmäßig 30 Tage nach der Registrierung beträgt, falls nicht ausdrücklich festgelegt. Beachten Sie, dass die Länge des Berichtsfensters weiter angepasst werden kann, indem ein aggregatable_report_window
-Wert im Attribution-Reporting-Register-Source
Header festgelegt wird. Siehe Benutzerdefinierte Berichtsfenster für weitere Details.
Hinweis: Um die Privatsphäre der Nutzer weiter zu schützen, haben die zusammenfassenden Berichtswerte, die mit jeder Attributionsquelle verbunden sind, einen endlichen Gesamtwert — dies wird als beitragsbudget bezeichnet. Dieser Wert kann bei verschiedenen Implementierungen der API variieren; in Chrome beträgt er 65.536. Alle Konversionen, die Berichte erzeugen würden, die Werte über diesem Limit hinzufügen, werden nicht aufgezeichnet. Stellen Sie sicher, dass Sie das Budget im Auge behalten und es zwischen den verschiedenen Metriken aufteilen, die Sie messen möchten.
Ein typischer aggregierbarer Bericht könnte folgendermaßen aussehen:
{
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"report_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"reporting_origin\":\"https://reporter.example\",\"scheduled_report_time\":\"1692255696\",\"source_registration_time\":\"1692230400\",\"version\":\"3\"}",
"aggregation_service_payloads": [
{
"payload": "[base64-encoded HPKE encrypted data readable only by the aggregation service]",
"key_id": "[string identifying public key used to encrypt payload]",
"debug_cleartext_payload": "[base64-encoded unencrypted payload]"
}
],
"aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com",
"source_debug_key": 647775351539539,
"trigger_debug_key": 647776891539539
}
Die Eigenschaften sind wie folgt:
-
Dies ist ein serialisiertes JSON-Objekt, das Informationen bietet, die ein Aggregationsdienst verwendet, um einen zusammenfassenden Bericht zu erstellen. Diese Daten werden verschlüsselt mit AEAD, um Manipulationen zu verhindern. Die folgenden Eigenschaften sind im serialisierten String enthalten:
"api"
-
Ein enumerierter Wert, der die API darstellt, die die Berichtserstellung ausgelöst hat. Derzeit wird dies immer
"attribution-reporting"
entsprechen, aber es kann in Zukunft mit zusätzlichen Werten erweitert werden, um andere APIs zu unterstützen. "attribution_destination"
-
Ein String, der die Attributions-
"destination"
-URL darstellt, die in der Quellregistrierung festgelegt wurde (über den zugehörigenAttribution-Reporting-Register-Source
Response-Header). "report_id"
-
Ein String, der eine Universally Unique Identifier (UUID) für diesen Bericht darstellt, der zur Verhinderung von doppeltem Zählen verwendet werden kann.
"reporting_origin"
-
Der Ursprung, der die Berichtserstellung ausgelöst hat.
"scheduled_report_time"
-
Ein String, der die Anzahl der Sekunden seit der Unix-Epoche darstellt, bis der Browser ursprünglich geplant hatte, den Bericht zu senden (um Ungenauigkeiten infolge von Offline-Geräten zu vermeiden, die verspätet berichten).
"source_registration_time"
-
Ein String, der die Anzahl der Sekunden seit der Unix-Epoche darstellt, bis die Attributionsquelle registriert wurde, auf einen ganzen Tag abgerundet.
"version"
-
Ein String, der die Version der API darstellt, die den Bericht erstellt hat.
"aggregation_service_payloads"
-
Ein Array von Objekten, das Nutzlastobjekte darstellt, die die Histogrammbeiträge enthalten, die der Aggregationsdienst verwendet, um die im Bericht enthaltenen Daten zusammenzustellen. Derzeit wird pro Bericht nur eine einzige Nutzlast unterstützt, die vom Browser konfiguriert wird. In Zukunft könnten mehrere, anpassbare Nutzlasten unterstützt werden. Jedes Nutzlastobjekt kann die folgenden Eigenschaften enthalten:
"payload"
-
Eine CBOR-Karte, die über HPKE verschlüsselt und dann base64-kodiert ist, mit folgender Struktur:
js{ "operation": "histogram", // Allows for the service to support other operations in the future "data": [{ "bucket": <bucket, encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>, "value": <value, encoded as a 4-byte (i.e. 32-bit) big-endian bytestring> }, ...] }
"key_id"
-
Ein String, der den öffentlichen Schlüssel identifiziert, der zur Verschlüsselung der Nutzlast verwendet wurde.
"debug_cleartext_payload"
Optional-
Optionale Debug-Informationen.
"aggregation_coordinator_origin"
-
Die Bereitstellungsoption für den Aggregationsdienst.
"source_debug_key"
Optional-
Ein 64-Bit-unsigned-Integer, der den Debugging-Schlüssel für die Attribution-Quelle darstellt. Dieser spiegelt den Wert wider, der im zugehörigen
Attribution-Reporting-Register-Source
Header's"debug_key"
-Feld festgelegt ist. Siehe Debug-Berichte für weitere Informationen. "trigger_debug_key"
Optional-
Ein 64-Bit-unsigned-Integer, der den Debugging-Schlüssel für den Attribution-Auslöser darstellt. Dieser spiegelt den Wert wider, der im zugehörigen
Attribution-Reporting-Register-Trigger
Header's"debug_key"
Feld festgelegt ist. Siehe Debug-Berichte für weitere Informationen.
Hinzufügen von Rauschen zu Berichten
Rauschen wird Berichten hinzugefügt, um die Ausgabe, die mit einer bestimmten Quelle verbunden ist, zu verschleiern und somit die Privatsphäre der Nutzer zu schützen. Die genauen Quelldaten können nicht identifiziert und individuellen Nutzern zugeschrieben werden, aber die gesamten Muster, die aus den Daten abgeleitet werden, liefern dennoch die gleiche Bedeutung.
Für Informationen darüber, wie Rauschen in der Attributionsberichterstattung funktioniert, siehe:
Prioritäten und Grenzen für Berichte
Standardmäßig haben alle Attributionsquellen die gleiche Priorität, und das Attributionsmodell ist last-touch, was bedeutet, dass eine Konversion der jüngsten passenden Quellenereignis zugeschrieben wird. Für sowohl Event-Level- als auch aggregierbare Berichte können Sie die Quellenpriorität ändern, indem Sie einen neuen Wert für das "priority"
-Feld im zugehörigen Attribution-Reporting-Register-Source
Header festlegen. Der Standardwert ist 0
; wenn Sie für eine bestimmte Quelle einen "priority"
-Wert von 1
festlegen, wird diese Quelle zuerst abgeglichen, vor allen Quellen mit der Priorität 0
. Quellen mit "priority": "2"
werden vor Quellen mit "priority": "1"
abgeglichen usw.
Die Prioritäten der Attributionsauslöser funktionieren auf die gleiche Weise; Sie können auch Auslöserprioritäten festlegen, indem Sie ein "priority"
-Feld im zugehörigen Attribution-Reporting-Register-Trigger
Header hinzufügen, aber nur für Event-Level-Berichte.
Verschiedene Quelltypen haben unterschiedliche Standardgrenzen:
- Navigationsbasierte Attributionsquellen haben standardmäßig eine Grenze von drei Berichten. Zum Beispiel, wenn ein Nutzer auf eine Anzeige klickt und viermal konvertiert: Er besucht die Startseite der Werbeseite, besucht dann eine Produktseite, meldet sich für den Newsletter an und tätigt schließlich einen Kauf. Der Kaufbericht wird verworfen, da er von der vierten Konversion stammt.
- Ereignisbasierte Attributionsquellen haben standardmäßig eine Grenze von einem Bericht.
Hinweis:
Die Berichtsgrenze kann angepasst werden, indem eine andere Anzahl von "end_times"
in den Feldern "event_report_windows"
des zugehörigen Attribution-Reporting-Register-Source
Headers festgelegt wird.
Wenn eine Attribution für ein gegebenes Quellenereignis ausgelöst wird und die maximale Anzahl von Attributierungen (drei für Klicks, eine für Bilder/Skripte) für diese Quelle erreicht ist, wird der Browser:
- Die Priorität des neuen Berichts mit den Prioritäten der bestehenden geplanten Berichte für diese gleiche Quelle vergleichen.
- Den Bericht mit der niedrigsten Priorität löschen, um den neuen Bericht stattdessen zu planen. Wenn der neue Bericht der mit der niedrigsten Priorität ist, wird er ignoriert und Sie erhalten ihn nicht.
Wenn keine Prioritäten festgelegt sind, fällt der Browser auf sein Standardverhalten zurück: Jede Konversion, die nach der dritten Konversion für Klicks oder der ersten Konversion für Ansichten erfolgt, wird verworfen.
Filter
Sie können Regeln definieren, welche Konversionen Berichte generieren, indem Sie Filter verwenden. Zum Beispiel könnten Sie sich entscheiden, nur Konversionen für eine bestimmte Produktkategorie zu zählen und Konversionen für andere Kategorien herauszufiltern.
Um Filter zu deklarieren:
-
Fügen Sie bei der Quellregistrierung ein
filter_data
-Feld zumAttribution-Reporting-Register-Source
Header hinzu, das die Filterkeys definiert, die Sie verwenden werden, um die Konversionen auf der Auslöserseite zu filtern. Diese sind völlig benutzerdefinierte Felder. Zum Beispiel, um nur Konversionen auf bestimmten Subdomains und für bestimmte Produkte anzugeben:json"filter_data": { "conversion_subdomain": ["electronics.megastore", "electronics2.megastore"], "product": ["1234"] }
-
Fügen Sie bei der Auslöserregistrierung ein
filters
-Feld zumAttribution-Reporting-Register-Trigger
Header hinzu. Das folgende Beispiel führt dazu, dass Auslöserinteraktionen mit der obigen Quellregistrierung übereinstimmen, da beide das"electronics.megastore"
-"conversion_subdomain"
-Feld enthalten. Der"directory"
-Filter hingegen wird ignoriert, wenn ein Abgleich versucht wird, da er nicht in der obigen Quellregistrierung enthalten war.json"filters": { "conversion_subdomain": ["electronics.megastore"], "directory": ["/store/electronics"] }
Wenn die "filter_data"
- und "filters"
-Felder übereinstimmende Unterfelder enthalten (wie "conversion_subdomain"
im obigen Beispiel), aber keiner der Werte des Unterfelds übereinstimmt, wird der Auslöser ignoriert, was zu keiner Übereinstimmung führt.
Filtern von Auslöserdaten
Das event_trigger_data
-Feld im Attribution-Reporting-Register-Trigger
Header kann erweitert werden, um selektives Filtern durchzuführen, um trigger_data
, priority
oder deduplication_key
basierend auf filter_data
festzulegen, das im Attribution-Reporting-Register-Source
Header definiert ist.
Zum Beispiel:
{
"event_trigger_data": [
{
"trigger_data": "2",
"filters": { "source_type": ["navigation"] }
},
{
"trigger_data": "1",
"filters": { "source_type": ["event"] }
}
]
}
Hinweis: "source_type"
ist ein automatisch gefülltes Feld, das in den "filter_data"
der Quelle verfügbar ist.
Hinweis: not_filters
, die mit Negation filtern, werden ebenfalls unterstützt.
In diesem Kontext kann filters
ein Objekt oder ein Array von Objekten sein. Wenn eine Liste angegeben ist, muss nur ein Wörterbuch übereinstimmen, damit der Auslöser als übereinstimmend betrachtet wird.
{
"event_trigger_data": [
{
"trigger_data": "2",
"filters": [
{
"product": ["1234"],
"conversion_subdomain": ["electronics.megastore"]
},
{
"product": ["4321"],
"conversion_subdomain": ["electronics4.megastore"]
}
]
}
]
}
Wenn die Filter für keine der Ereignisauslöser übereinstimmen, wird kein Event-Level-Bericht erstellt. Wenn die Filter für mehrere Ereignisauslöser übereinstimmen, wird der erste übereinstimmende Ereignisauslöser verwendet.
Debug-Berichte
Sie können Debug-Berichte aktivieren, um Fehlerbehebungsinformationen zu Ihren Attributionsberichten zurückzugeben. Diese können beispielsweise verwendet werden, um zu überprüfen, ob Ihre Einrichtung ordnungsgemäß funktioniert, und um Lücken in den Messungsergebnissen zwischen Ihrer alten Cookie-basierten Implementierung und Ihrer neuen Attribution Reporting Implementierung zu verstehen. Debug-Berichte werden sofort gesendet; sie unterliegen nicht dem gleichen Zeitplan wie Event-Level- und zusammenfassende Berichte.
Es gibt zwei verschiedene Arten von Debug-Berichten:
- Erfolgs-Debug-Berichte verfolgen die erfolgreiche Erstellung eines spezifischen Attributionsberichts. Erfolgs-Debug-Berichte werden generiert und gesendet, sobald der entsprechende Auslöser registriert ist.
- Verbose-Debug-Berichte geben Ihnen mehr Einblick in die Attributionsquellen- und Attributionsauslöserereignisse, die mit einem Attributionsbericht verbunden sind. Sie ermöglichen Ihnen sicherzustellen, dass Quellen erfolgreich registriert wurden oder fehlende Berichte nachzuverfolgen und zu bestimmen, warum sie fehlen (zum Beispiel aufgrund von Fehlern bei der Quellen- oder Auslöserereignisregistrierung oder Fehlern beim Senden oder Erstellen des Berichts). Verbose-Debug-Berichte werden sofort bei Quellen- oder Auslöserregistrierung gesendet.
Hinweis: Um Debug-Berichte zu verwenden, muss der Reporting-Ursprung ein Cookie setzen. Wenn der Ursprung, der Berichte empfängt, ein Drittanbieter ist, wird dieses Cookie ein Third-Party-Cookie sein, was bedeutet, dass Debug-Berichte in Browsern, in denen Third-Party-Cookies deaktiviert/nicht verfügbar sind, nicht verfügbar sein werden.
Verwendung von Debug-Berichten
Um Debug-Berichte zu verwenden, müssen Sie:
-
Setzen Sie das
ar_debug
-Cookie auf Ihrem Reporting-Ursprung. Dieses muss sowohl während der Quellen- als auch der Auslöserregistrierung vorhanden sein:httpSet-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
-
Setzen Sie das
debug_key
-Feld in allen zugehörigenAttribution-Reporting-Register-Source
undAttribution-Reporting-Register-Trigger
Antwort-Headern, die sich auf Attributionsberichte beziehen, für die Sie Debug-Informationen freigeben möchten. Jederdebug_key
-Wert muss ein 64-Bit-unsigned-Integer sein, das im Base-10-Format ist. Machen Sie jeden Debug-Schlüssel zu einer eindeutigen ID — Sie könnten zum Beispiel jeden als Cookie-ID + Quellen-/Auslöser-Zeitsignatur festlegen (und diese gleiche Zeitsignatur in Ihrem älteren Cookie-basierten System erfassen, wenn Sie die beiden vergleichen möchten).json{ "debug_key": "647775351539539" }
Hinweis: Machen Sie den auf der Quellen-Seite liegenden Debug-Schlüssel anders als die
source_event_id
, damit Sie einzelne Berichte unterscheiden können, die die gleiche Quellen-Ereignis-ID haben. -
Optional setzen Sie das
debug_reporting
-Feld auftrue
, sowohl in denAttribution-Reporting-Register-Source
- als auchAttribution-Reporting-Register-Trigger
-Headern. Wenn Sie dies tun, wird ein verboser Debug-Bericht erstellt. Wenn Sie dies nicht tun, wird ein Erfolgs-Debug-Bericht erstellt, der die Art des Attributionsberichts widerspiegelt, den Sie erstellen (Event-Level oder aggregierbar).json{ "debug_key": "647775351539539", "debug_reporting": true }
-
Richten Sie geeignete Endpunkte ein, um die Debug-Berichte zu empfangen, die Sie erstellen möchten. Debug-Berichte werden an drei separate Endpunkte im Reporting-Ursprung gesendet:
- Endpunkt für Event-Level-Erfolgs-Debug-Berichte:
<reporting-origin>/.well-known/attribution-reporting/debug/report-event-attribution
- Endpunkt für aggregierbare Erfolgs-Debug-Berichte:
<reporting-origin>/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Endpunkt für verbose Debug-Berichte:
<reporting-origin>/.well-known/attribution-reporting/debug/verbose
- Endpunkt für Event-Level-Erfolgs-Debug-Berichte:
Generierte Erfolgs-Debug-Berichte sind identisch mit Attributionsberichten und enthalten die auf der Quellen-Seite und Auslöser-Seite liegenden Debug-Schlüssel in den "source_debug_key"
und "trigger_debug_key"
Feldern jeweils.
Für weitere Informationen und Beispiele siehe:
- Einführung zu Debug-Berichten auf developers.google.com (2023)
- Setup von Debug-Berichten auf developers.google.com (2023)
- Debugging Cookbook auf developers.google.com (2023)