Generieren von Attributionsberichten

Wenn ein Abgleich zwischen einem Trigger und einer Quelle stattfindet, generiert der Browser einen Bericht und sendet ihn über eine nicht authentifizierte POST-Anfrage an ein spezifisches Endpunkt der Berichterstattungs-Quelle:

• Für Berichte auf Ereignisebene 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> wird gleichen Ursprungs sein mit dem, der die Quelle und den Trigger registriert hat.

Die Berichtsdaten sind in einer JSON-Struktur enthalten.

Berichte auf Ereignisebene werden generiert und geplant, um am Ende ihres enthaltenen Berichtsfensters gesendet zu werden. Die Länge des Berichtsfensters wird durch die Werte bestimmt, die im Feld "event_report_window" oder "event_report_windows" im Header der Quelle Attribution-Reporting-Register-Source festgelegt sind.

Wenn keines dieser Felder angegeben ist, fällt das Berichtsfenster auf die folgenden Standardwerte zurück:

• Für ereignisbasierte Quellen endet das standardmäßige Berichtsfenster mit dem Ablauf der Quelle, der im Attribution-Reporting-Register-Source-Feld "expiry" festgelegt ist. Wenn nicht explizit festgelegt, beträgt es standardmäßig 30 Tage nach der Registrierung.
• Für navigationsbasierte Quellen sind die standardmäßigen Berichtsfenster 2 Tage, 7 Tage und der "expiry"-Wert der Quelle.

Weitere Informationen finden Sie unter Benutzerdefinierte Berichtsfenster.

Sobald ein Bericht auf Ereignisebene am entsprechenden Endpunkt eingegangen ist, liegt es vollständig beim Entwickler, wie die Daten verarbeitet, gespeichert und angezeigt werden. Ein typischer Bericht auf Ereignisebene könnte so 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, abhängig davon, ob die Quelle mit mehreren Zielen registriert wurde oder nicht. Diese Strings repräsentieren die im Zuge der damit verbundenen Attribution-Reporting-Register-Source-Antwortheader in der Quellregistrierung festgelegten Attributions"destination"-Seiten.

"source_event_id"

Ein String, der die Attributionsquellen-ID repräsentiert. Dieser entspricht der "source_event_id", die in der Quellregistrierung im Zuge des damit verbundenen Attribution-Reporting-Register-Source-Antwortheaders festgelegt ist.

"trigger_data"

Ein String, der Daten vom Attributionstrigger repräsentiert, die bei der Triggerregistrierung festgelegt wurden (die "trigger_data", die über den damit verbundenen Attribution-Reporting-Register-Trigger-Antwortheader festgelegt wurden).

"report_id"

Ein String, der eine Universally Unique Identifier (UUID) für diesen Bericht repräsentiert, der zur Verhinderung doppelter Zählung verwendet werden kann.

"source_type"

Ein String, der entweder "navigation" oder "event" entspricht, was jeweils angibt, ob die zugehörige Attributionsquelle navigationsbasiert oder ereignisbasiert ist.

"randomized_trigger_rate"

Eine Zufallszahl zwischen 0 und 1, die angibt, wie oft Rauschen für diese bestimmte Quellenkonfiguration angewendet wird.

"scheduled_report_time"

Ein String, der die Anzahl der Sekunden von der Unix-Epoche bis zur ursprünglichen Planung des Berichts durch den Browser darstellt (um Unstimmigkeiten aufgrund verspäteter Berichterstattung durch Offline-Geräte zu vermeiden).

"source_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debugging-Schlüssel für die Attributionsquelle darstellt. Dieser spiegelt den Wert wider, der im entsprechenden "debug_key"-Feld des Attribution-Reporting-Register-Source-Headers festgelegt ist. Weitere Informationen finden Sie unter Debug-Berichte.

"trigger_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debugging-Schlüssel für den Attributionstrigger darstellt. Dieser spiegelt den Wert wider, der im "debug_key"-Feld des entsprechenden Attribution-Reporting-Register-Trigger-Headers festgelegt ist. Weitere Informationen finden Sie unter Debug-Berichte.

Ein zusammenfassender Bericht wird aus mehreren aggregierbaren Berichten erstellt, die am entsprechenden Endpunkt eingegangen sind, und dann gebündelt, um sie zur Verarbeitung durch einen Aggregationsdienst vorzubereiten. Sobald dies geschehen ist, liegt es vollständig beim Entwickler, wie die Daten verarbeitet, gespeichert und angezeigt werden.

Ein aggregierbarer Bericht wird standardmäßig generiert und geplant, um nach einer Interaktion mit einem Trigger mit einer zufälligen Verzögerung gesendet zu werden, um die zeitliche Präzision zu verschleiern und die Privatsphäre zu verbessern. Für eine gegebene registrierte Attributionsquelle werden Attributionsquellenereignisse von der Registrierung bis zum Ablauf der Quelle aufgezeichnet - dies wird als Berichtsfenster bezeichnet.

Die Ablaufzeit wird durch den expiry-Wert im zugehörigen Attribution-Reporting-Register-Source-Header definiert, der standardmäßig 30 Tage nach der Registrierung beträgt, wenn nicht ausdrücklich festgelegt. Beachten Sie, dass die Länge des Berichtsfensters weiter modifiziert werden kann, indem ein aggregatable_report_window-Wert im Attribution-Reporting-Register-Source-Header festgelegt wird. Weitere Informationen finden Sie unter Benutzerdefinierte Berichtsfenster.

Ein typischer aggregierbarer Bericht könnte so 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:

"shared_info"

Dies ist ein serialisiertes JSON-Objekt, das Informationen bereitstellt, die ein Aggregationsdienst benötigt, um einen zusammenfassenden Bericht zu erstellen. Diese Daten sind verschlüsselt mit AEAD, um eine Manipulation zu verhindern. Die folgenden Eigenschaften sind im serialisierten String dargestellt:

"api"

Ein enumerierter Wert, der die API darstellt, die das Berichtsereignis ausgelöst hat. Derzeit wird er immer "attribution-reporting" sein, kann aber in Zukunft mit zusätzlichen Werten erweitert werden, um andere APIs zu unterstützen.

"attribution_destination"

Ein String, der die in der Quellregistrierung über den zugehörigen Attribution-Reporting-Register-Source-Antwortheader festgelegte Attributions"destination"-URL repräsentiert.

"report_id"

Ein String, der einen Universally Unique Identifier (UUID) für diesen Bericht repräsentiert, der zur Verhinderung doppelter Zählung verwendet werden kann.

"reporting_origin"

Der Ursprung, der die Berichterstellung ausgelöst hat.

"scheduled_report_time"

Ein String, der die Anzahl der Sekunden von der Unix-Epoche bis zur ursprünglichen Planung des Berichts durch den Browser darstellt (um Unstimmigkeiten aufgrund verspäteter Berichterstattung durch Offline-Geräte zu vermeiden).

"source_registration_time"

Ein String, der die Anzahl der Sekunden von der Unix-Epoche bis zur Registrierung der Attributionsquelle darstellt, abgerundet auf einen ganzen Tag.

"version"

Ein String, der die Version der API repräsentiert, die zur Erstellung des Berichts verwendet wurde.

"aggregation_service_payloads"

Ein Array von Objekten, das Nutzlastobjekte repräsentiert, die die Histogrammbeiträge enthalten, die vom Aggregationsdienst verwendet werden, 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 wird, mit folgender Struktur (nur zur Notation mit JSON):

jsonCopy to Clipboard

{
  "operation": "histogram",
  "data": [
    {
      "bucket": "<Encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>",
      "value": "<Encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>"
    }
    // …
  ]
}

Die operation ist immer "histogram"; es erlaubt, dass der Dienst in Zukunft andere Operationen unterstützt.

"key_id"

Ein String, der den öffentlichen Schlüssel identifiziert, mit dem die Nutzlast verschlüsselt wurde.

"debug_cleartext_payload" Optional

Optionale Debugging-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 Attributionsquelle darstellt. Dieser spiegelt den Wert wider, der im entsprechenden "debug_key"-Feld des Attribution-Reporting-Register-Source-Headers festgelegt ist. Weitere Informationen finden Sie unter Debug-Berichte.

"trigger_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debugging-Schlüssel für den Attributionstrigger darstellt. Dieser spiegelt den Wert wider, der im "debug_key"-Feld des entsprechenden Attribution-Reporting-Register-Trigger-Headers festgelegt ist. Weitere Informationen finden Sie unter Debug-Berichte.

Rauschen wird Berichten hinzugefügt, um die mit einer bestimmten Quelle verbundenen Ausgaben zu verschleiern und dadurch die Privatsphäre der Benutzer zu schützen. Die genauen Quelldaten können nicht identifiziert und einzelnen Benutzern zugeordnet werden, aber die insgesamt aus den Daten abgeleiteten Muster behalten die gleiche Bedeutung.

Für Informationen darüber, wie Rauschen in der Attributionsberichterstattung funktioniert, siehe:

• Verständnis von Rauschen in zusammenfassenden Berichten.
• Datenlimits und Rauschen
• Arbeiten mit Rauschen

Standardmäßig haben alle Attributionsquellen die gleiche Priorität und das Attributionsmodell ist zuletzt berührend, was bedeutet, dass eine Umwandlung der zuletzt passenden Quellenereignis zugeschrieben wird. Für sowohl Berichte auf Ereignisebene 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 einen "priority"-Wert von 1 für eine bestimmte Quelle festlegen, wird diese Quelle zuerst abgeglichen, vor allen Quellen mit Priorität 0. Quellen mit "priority": "2" werden vor Quellen mit "priority": "1" abgeglichen, und so weiter.

Attributionstrigger-Prioritäten funktionieren auf die gleiche Weise; Sie können auch Trigger-Prioritäten festlegen, indem Sie ein "priority"-Feld zum zugehörigen Attribution-Reporting-Register-Trigger-Header hinzufügen, jedoch nur für Berichte auf Ereignisebene.

Verschiedene Quelltypen haben unterschiedliche Standardgrenzen:

• Navigationsbasierte Attributionsquellen haben standardmäßig ein Drei-Berichts-Limit. Wenn ein Nutzer beispielsweise auf eine Anzeige klickt und viermal konvertiert: Sie besuchen die Homepage des Werbetreibenden, dann eine Produktseite, melden sich für den Newsletter an und tätigen schließlich einen Kauf. Der Kaufbericht wird verworfen, da er aus der vierten Konvertierung stammt.
• Ereignisbasierte Attributionsquellen haben standardmäßig ein Ein-Berichts-Limit.

Wenn eine Attribution für ein bestimmtes Quellenereignis ausgelöst wird und die maximale Anzahl von Attributionen (drei für Klicks, eine für Bilder/Skripte) für diese Quelle erreicht wurde, wird der Browser:

• Die Priorität des neuen Berichts mit den Prioritäten der bestehenden geplanten Berichte für dieselbe Quelle vergleichen.
• Den Bericht mit der niedrigsten Priorität löschen, um stattdessen den neuen Bericht 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 Konvertierung nach der dritten Konvertierung für Klicks oder der ersten Konvertierung für Ansichten wird fallen gelassen.

Sie können Regeln festlegen, welche Konvertierungen Berichte generieren, indem Sie Filter verwenden. Beispielsweise könnten Sie sich dafür entscheiden, nur Konvertierungen für eine bestimmte Produktkategorie zu zählen und Konvertierungen für andere Kategorien herauszufiltern.

Um Filter zu deklarieren:

1. Fügen Sie bei der Quellenregistrierung ein filter_data-Feld zum Attribution-Reporting-Register-Source-Header hinzu, das die Filter-Schlüssel definiert, die Sie verwenden möchten, um die Konvertierungen auf der Trigger-Seite zu filtern. Diese sind vollständig benutzerdefinierte Felder. Um beispielsweise nur Konvertierungen auf bestimmten Subdomains und für bestimmte Produkte anzugeben:

   jsonCopy to Clipboard

   "filter_data": {
     "conversion_subdomain": ["electronics.megastore", "electronics2.megastore"],
     "product": ["1234"]
   }
   

2. Fügen Sie bei der Triggerregistrierung ein filters-Feld zum Attribution-Reporting-Register-Trigger-Header hinzu. Das Folgende verursacht beispielsweise, dass Trigger-Interaktionen die oben genannte Quellenregistrierung abgleichen, da beide das "electronics.megastore"-"conversion_subdomain"-Feld enthalten. Der "directory"-Filter wiederum wird ignoriert, wenn ein Abgleich versucht wird, da er nicht in der oben genannten Quellenregistrierung enthalten war.

   jsonCopy to Clipboard

   "filters": {
     "conversion_subdomain": ["electronics.megastore"],
     "directory": ["/store/electronics"]
   }
   

Wenn die Felder "filter_data" und "filters" übereinstimmende Unterfelder enthalten (wie "conversion_subdomain" im obigen Beispiel), aber keiner der Unterfeld-Werte übereinstimmt, wird der Trigger ignoriert, was zu keinem Abgleich führt.

Das event_trigger_data-Feld im Attribution-Reporting-Register-Trigger-Header kann erweitert werden, um selektives Filtern vorzunehmen, um trigger_data, priority oder deduplication_key basierend auf dem im Attribution-Reporting-Register-Source-Header definierten filter_data festzulegen.

Beispielsweise:

{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": { "source_type": ["navigation"] }
    },
    {
      "trigger_data": "1",
      "filters": { "source_type": ["event"] }
    }
  ]
}

In diesem Kontext kann filters ein Objekt oder ein Array von Objekten sein. Wenn eine Liste angegeben ist, muss nur ein Dictionary übereinstimmen, damit der Trigger berücksichtigt 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 keinen der Ereignistrigger übereinstimmen, wird kein Bericht auf Ereignisebene erstellt. Wenn die Filter für mehrere Ereignistrigger übereinstimmen, wird der erste übereinstimmende Ereignistrigger verwendet.

Sie können Debug-Berichte aktivieren, um Informationen zur Fehlersuche über Ihre Attributionsberichte zurückzugeben. Diese können beispielsweise verwendet werden, um zu überprüfen, ob Ihre Einrichtung ordnungsgemäß funktioniert, und Lücken in den Messergebnissen 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 Berichte auf Ereignisebene und Zusammenfassungsberichte.

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 Trigger registriert ist.
• Detailierte Debug-Berichte geben Ihnen mehr Einblick in die Attributionsquellen- und Attributionstrigger-Ereignisse, die mit einem Attributionsbericht verbunden sind. Sie ermöglichen es Ihnen zu gewährleisten, dass Quellen erfolgreich registriert wurden, fehlende Berichte zu verfolgen und zu bestimmen, warum sie fehlen (zum Beispiel aufgrund eines Fehlschlags bei der Registrierung von Quellen- oder Triggerereignissen oder eines Fehlschlags beim Senden oder Generieren des Berichts). Detailierte Debug-Berichte werden sofort bei der Registrierung von Quellen oder Triggern gesendet.

Um Debug-Berichte zu verwenden, müssen Sie:

1. Das ar_debug-Cookie auf Ihrem Berichterstattungsursprung setzen. Dies muss sowohl bei der Quellen- als auch bei der Triggerregistrierung vorhanden sein:

   httpCopy to Clipboard

   Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
   

2. Das debug_key-Feld in allen zu den Attributionsberichten gehörenden Attribution-Reporting-Register-Source- und Attribution-Reporting-Register-Trigger-Antwortheadern setzen, für die Sie Debug-Informationen anzeigen möchten. Jeder debug_key-Wert muss ein als Basis-10-Zeichenkette formatierter 64-Bit-unsigned Integer sein. Machen Sie jeden Debug-Schlüssel zu einer eindeutigen ID – Sie könnten beispielsweise jeden als Cookie-ID + Quellen/Trigger-Zeitstempel setzen (und denselben Zeitstempel in Ihrem älteren Cookie-basierten System erfassen, wenn Sie die beiden vergleichen möchten).

   jsonCopy to Clipboard

   {
     "debug_key": "647775351539539"
   }
   

   Hinweis: Machen Sie den Debug-Schlüssel auf der Quellenseite anders als die source_event_id, damit Sie einzelne Berichte mit derselben Quellenseiten-ID unterscheiden können.

3. Optional, das debug_reporting-Feld auf true setzen, sowohl in den Attribution-Reporting-Register-Source- und Attribution-Reporting-Register-Trigger-Headers. Wenn Sie dies tun, wird ein detaillierter Debug-Bericht generiert. Wenn Sie dies nicht tun, wird ein erfolgreicher Debug-Bericht generiert, der die Art des Attributionsberichts widerspiegelt, den Sie generieren (auf Ereignisebene oder aggregierbar).

   jsonCopy to Clipboard

   {
     "debug_key": "647775351539539",
     "debug_reporting": true
   }
   

4. Richtige Endpunkte einrichten, um die Debug-Berichte zu empfangen, die Sie generieren möchten. Debug-Berichte werden an drei separate Endpunkte in der Berichterstattungsquelle gesendet:

   • Endpunkt für Erfolgs-Debug-Berichte auf Ereignisebene: <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 detailierte Debug-Berichte: <reporting-origin>/.well-known/attribution-reporting/debug/verbose

Generierte Erfolgs-Debug-Berichte sind mit Attributionsberichten identisch und enthalten die auf der Quellseite und der Trägerseite befindlichen Debug-Schlüssel in den jeweils "source_debug_key"- und "trigger_debug_key"-Felder.

Für weitere Informationen und Beispiele siehe:

• Einführung in Debug-Berichte auf privacysandbox.google.com (2023)
• Einrichten von Debug-Berichten auf privacysandbox.google.com (2023)
• Debugging-Kochbuch auf privacysandbox.google.com (2023)