Generierung von Attributionsberichten

Grundlegender Prozess

Wenn eine Übereinstimmung zwischen einem Auslöser und einer Quelle auftritt, generiert der Browser einen Bericht und sendet ihn über eine nicht authentifizierte POST-Anforderung an einen bestimmten Endpunkt im Berichtursprung:

• 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> ist bei der Registrierung der Quelle und des Auslösers gleichherkunftsmäßig.

Die Berichtsdaten sind in einer JSON-Struktur enthalten.

Berichte auf Ereignisebene

Berichte auf Ereignisebene werden erstellt und zur Versendung am Ende ihres enthaltenen Berichtszeitfensters geplant. Die Länge des Berichtszeitfensters wird durch die im Feld "event_report_window" oder "event_report_windows" des Headers Attribution-Reporting-Register-Source der Quelle festgelegten Werte bestimmt.

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

• Für ereignisbasierte Quellen endet das Standardberichtszeitfenster mit dem Ablauf der Quelle, der im Attribution-Reporting-Register-Source-Feld für "expiry" festgelegt ist. Dies ist standardmäßig 30 Tage nach der Registrierung, wenn nicht explizit festgelegt.
• Für navigationsbasierte Quellen beträgt das Standardberichtszeitfenster 2 Tage, 7 Tage und die "expiry" der Quelle.

Siehe Benutzerdefinierte Berichtszeitfenster für weitere Details.

Sobald ein Bericht auf Ereignisebene am entsprechenden Endpunkt eingegangen ist, liegt es vollständig im Ermessen des Entwicklers, 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, je nachdem, ob die Quelle mit mehreren Zielen registriert wurde oder nicht. Diese Strings repräsentieren die Attributionsseite(n) "destination", die in der Quellenregistrierung über den zugehörigen Attribution-Reporting-Register-Source Antwortheader festgelegt sind.

"source_event_id"

Ein String, der die Attributionsquellen-ID darstellt. Dies entspricht dem in der Quellenregistrierung festgelegten "source_event_id" (über den zugehörigen Attribution-Reporting-Register-Source Antwortheader).

"trigger_data"

Ein String, der Daten darstellt, die vom Attributionstrigger stammen und in der Triggersregistrierung festgelegt sind (das "trigger_data", das über den zugehörigen Attribution-Reporting-Register-Trigger Antwortheader festgelegt ist).

"report_id"

Ein String, der eine Universally Unique Identifier (UUID) für diesen Bericht repräsentiert, der verwendet werden kann, um doppelte Zählungen zu verhindern.

"source_type"

Ein String, der entweder "navigation" oder "event" entspricht und anzeigt, 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 seit der Unix-Epoche darstellt, bis der Browser den Bericht ursprünglich geplant hat, um Ungenauigkeiten zu vermeiden, die durch verspätete Berichte von Offline-Geräten verursacht werden.

"source_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debug-Schlüssel für die Attributionsquelle darstellt. Dies spiegelt den im zugehörigen Attribution-Reporting-Register-Source Header festgelegten Wert "debug_key" wider. Siehe Debug-Berichte für weitere Informationen.

"trigger_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debug-Schlüssel für den Attributionstrigger darstellt. Dies spiegelt den im zugehörigen Attribution-Reporting-Register-Trigger Header festgelegten "debug_key" Wert wider. Siehe Debug-Berichte für weitere Informationen.

Zusammenfassende Berichte

Ein zusammenfassender Bericht wird aus mehreren aggregierbaren Berichten erstellt, die am entsprechenden Endpunkt empfangen und dann batchweise vorbereitet werden, um von einem Aggregationsdienst verarbeitet zu werden. Sobald dies geschehen ist, liegt es vollständig im Ermessen des Entwicklers, wie die Daten verarbeitet, gespeichert und angezeigt werden.

Ein aggregierbarer Bericht wird standardmäßig nach einer Interaktion mit einem Auslöser erstellt und zur Versendung geplant, mit einer zufälligen Verzögerung, um die Zeitmessungen zu verschleiern und die Privatsphäre zu verbessern. Für eine gegebene registrierte Attributionsquelle werden Attributionsquellen-Ereignisse von der Registrierung bis zum Ablaufen der Quelle aufgezeichnet - dies wird als Berichtszeitfenster bezeichnet.

Die Ablaufzeit wird durch den im zugehörigen Attribution-Reporting-Register-Source Header festgelegten expiry-Wert definiert, der standardmäßig 30 Tage nach der Registrierung beträgt, wenn nicht explizit festgelegt. Beachten Sie, dass die Länge des Berichtszeitfensters durch Festlegung eines aggregatable_report_window-Werts im Attribution-Reporting-Register-Source Header weiter modifiziert werden kann. Siehe Benutzerdefinierte Berichtszeitfenster für weitere Details.

Ein typischer aggregierbarer Bericht könnte wie folgt 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 verwendet, um einen zusammenfassenden Bericht zu erstellen. Diese Daten sind verschlüsselt unter Verwendung von AEAD, um Manipulationen zu verhindern. Die folgenden Eigenschaften sind im serialisierten String enthalten:

"api"

Ein enumerierter Wert, der die API repräsentiert, die die Berichterstellung ausgelöst hat. Derzeit wird dies immer "attribution-reporting" sein, könnte jedoch in Zukunft um zusätzliche Werte erweitert werden, um andere APIs zu unterstützen.

"attribution_destination"

Ein String, der die Attributions-URL "destination" darstellt, die in der Quellenregistrierung (über den zugehörigen Attribution-Reporting-Register-Source Antwortheader) festgelegt ist.

"report_id"

Ein String, der eine Universally Unique Identifier (UUID) für diesen Bericht repräsentiert, der verwendet werden kann, um doppelte Zählungen zu verhindern.

"reporting_origin"

Der Ursprung, der die Berichtsgenerierung ausgelöst hat.

"scheduled_report_time"

Ein String, der die Anzahl der Sekunden seit der Unix-Epoche darstellt, bis der Browser den Bericht ursprünglich geplant hat, um Ungenauigkeiten zu vermeiden, die durch verspätete Berichte von Offline-Geräten verursacht werden.

"source_registration_time"

Ein String, der die Anzahl der Sekunden seit der Unix-Epoche darstellt, bis die Attributionsquelle registriert wurde, abgerundet auf einen ganzen Tag.

"version"

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

"aggregation_service_payloads"

Ein Array von Objekten, die Payload-Objekte repräsentieren, die die Histogrammbeiträge enthalten, die vom Aggregationsdienst verwendet werden, um die im Bericht enthaltenen Daten zusammenzustellen. Derzeit wird in jedem Bericht nur eine einzelne Nutzlast unterstützt, die vom Browser konfiguriert wird. In Zukunft könnten mehrere, anpassbare Nutzlasten unterstützt werden. Jedes Payload-Objekt kann die folgenden Eigenschaften enthalten:

"payload"

Eine CBOR Map, die mit HPKE verschlüsselt und dann base64-codiert wird, mit folgender Struktur (nur zur Veranschaulichung in JSON-Notation):

json

{
  "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 ermöglicht dem Dienst, in Zukunft andere Operationen zu unterstützen.

"key_id"

Ein String, der den öffentlichen Schlüssel identifiziert, der zur Verschlüsselung der Nutzlast verwendet wurde.

"debug_cleartext_payload" Optional

Optionales Debugging-Informationen.

"aggregation_coordinator_origin"

Die Implementierungsoption für den Aggregationsdienst.

"source_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debug-Schlüssel für die Attributionsquelle darstellt. Dies spiegelt den im zugehörigen Attribution-Reporting-Register-Source Header festgelegten Wert "debug_key" wider. Siehe Debug-Berichte für weitere Informationen.

"trigger_debug_key" Optional

Ein 64-Bit-unsigned Integer, der den Debug-Schlüssel für den Attributionstrigger darstellt. Dies spiegelt den im zugehörigen Attribution-Reporting-Register-Trigger Header festgelegten "debug_key" Wert wider. Siehe Debug-Berichte für weitere Informationen.

Hinzufügen von Rauschen zu Berichten

Rauschen wird Berichten hinzugefügt, um die Zuordnung der Ausgabe zu einer bestimmten Quelle zu verschleiern und somit die Privatsphäre der Nutzer zu schützen. Die genauen Quelldaten können nicht identifiziert und einzelnen Nutzern zugeordnet werden, aber die übergeordneten Muster, die aus den Daten abgeleitet werden, haben immer noch dieselbe Bedeutung.

Für Informationen über die Funktionsweise von Rauschen im Attributionsbericht, sehen Sie:

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

Berichtprioritäten und -limits

Standardmäßig haben alle Attributionsquellen die gleiche Priorität, und das Attributionsmodell basiert auf dem letzten Kontakt, was bedeutet, dass eine Konversion der zuletzt passenden Quellenereignis zugeordnet 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 auf eine bestimmte Quelle setzen, wird diese Quelle zuerst abgeglichen, vor jeglichen Priorität-0-Quellen. Quellen mit "priority": "2" werden vor "priority": "1"-Quellen abgeglichen, und so weiter.

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

Verschiedene Quellentypen haben unterschiedliche Standardlimits:

• Navigationsbasierte Attributionsquellen haben standardmäßig ein Dreiberichtelimit. Nehmen wir an, ein Nutzer klickt auf eine Anzeige und konvertiert vier Mal: Sie besuchen die Homepage der Werbeseite, besuchen dann eine Produktseite, melden sich für den Newsletter an und tätigen schließlich einen Kauf. Der Kaufbericht würde nicht berücksichtigt, da er auf die vierte Konversion zurückgeht.
• Ereignisbasierte Attributionsquellen haben standardmäßig ein Einberichtelimit.

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

• Die Priorität des neuen Berichts mit den Prioritäten der vorhandenen geplanten Berichte für dieselbe Quelle vergleichen.
• Den Bericht mit der niedrigsten Priorität löschen, um den neuen Bericht stattdessen zu planen. Wenn der neue Bericht derjenige 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 für Klicks oder der ersten für Ansichten erfolgt, wird verworfen.

Filter

Sie können Regeln festlegen, welche Konversionen Berichte generieren, indem Sie Filter verwenden. Zum Beispiel könnten Sie wählen, nur Konversionen für eine bestimmte Produktkategorie zu zählen und Konversionen für andere Kategorien zu filtern.

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, um die Konversionen auf der Auslöserseite zu filtern. Dies sind vollständig 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"]
     }
   }
   

2. Fügen Sie bei der Triggerregistrierung ein filters-Feld zum Attribution-Reporting-Register-Trigger Header hinzu. Das Folgende führt zum Beispiel dazu, dass Trigger-Interaktionen mit der obigen Quellenregistrierung übereinstimmen, da sie beide das "electronics.megastore" "conversion_subdomain"-Feld enthalten. Der "directory"-Filter hingegen wird ignoriert, wenn versucht wird, eine Übereinstimmung herzustellen, da er nicht in der oben genannten Quellenregistrierung enthalten war.

   json

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

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

Filterung von Triggerdaten

Das event_trigger_data-Feld im Attribution-Reporting-Register-Trigger Header kann erweitert werden, um selektive Filterung durchzuführen, um trigger_data, priority oder deduplication_key basierend auf filter_data, das im Attribution-Reporting-Register-Source Header definiert ist, festzulegen.

Zum Beispiel:

{
  "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 Wörterbuch ü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 keine der Ereignisauslöser übereinstimmen, wird kein Bericht auf Ereignisebene 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 Informationen zur Fehlerbehebung über Ihre Attributionsberichte zurückzugeben. Diese können beispielsweise verwendet werden, um zu überprüfen, ob Ihre Einrichtung ordnungsgemäß funktioniert und um 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 derselben Zeitplanung wie Berichte auf Ereignisebene und zusammenfassende Berichte.

Es gibt zwei verschiedene Arten von Debug-Berichten:

• Erfolgs-Debug-Berichte verfolgen die erfolgreiche Erstellung eines bestimmten Attributionsberichts. Erfolgs-Debug-Berichte werden generiert und gesendet, sobald der entsprechende Trigger registriert ist.
• Ausführliche Debug-Berichte geben Ihnen mehr Einblick in die Attributionsquelle und die Attributions-Ereignisse, die mit einem Attributionsbericht verbunden sind. Sie ermöglichen Ihnen, sicherzustellen, dass Quellen erfolgreich registriert wurden, oder fehlende Berichte zu verfolgen und zu bestimmen, warum sie fehlen (zum Beispiel aufgrund eines Fehlers bei der Registrierung des Quell- oder Triggerereignisses oder eines Fehlers beim Senden oder Generieren des Berichts). Ausführliche Debug-Berichte werden sofort bei der Registrierung der Quelle oder des Triggers gesendet.

Verwendung von Debug-Berichten

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

1. Das ar_debug-Cookie auf Ihrem Berichtsursprung setzen. Dieses muss sowohl während der Quelle- als auch der Triggerregistrierung vorhanden sein:

   http

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

2. Das debug_key-Feld in allen Antwortheadern Attribution-Reporting-Register-Source und Attribution-Reporting-Register-Trigger für Attributionsberichte festlegen, für die Sie Debugging-Informationen offenlegen möchten. Jeder debug_key-Wert muss ein 64-Bit-unsigned Integer im Basis-10-String-Format sein. Machen Sie jeden Debug-Schlüssel zu einer eindeutigen ID - Sie könnten zum Beispiel jeden als Cookie-ID + Zeitstempel des Quelle-/Triggersatzes festlegen (und diesen gleichen Zeitstempel in Ihrem älteren Cookie-basierten System erfassen, wenn Sie die beiden vergleichen möchten).

   json

   {
     "debug_key": "647775351539539"
   }
   

   Hinweis: Machen Sie den Debug-Schlüssel auf der Quellseite unterschiedlich zu source_event_id, damit Sie einzelne Berichte unterscheiden können, die dieselbe Quellereignis-ID haben.

3. Optional das debug_reporting-Feld auf true in beiden Attribution-Reporting-Register-Source- und Attribution-Reporting-Register-Trigger-Headern setzen. Wenn Sie dies tun, wird ein ausführlicher Debug-Bericht generiert. Wenn Sie dies nicht tun, wird ein erfolgreicher Debug-Bericht erzeugt, der den Typ des Attributionsberichts widerspiegelt, den Sie generieren (auf Ereignisebene oder aggregierbar).

   json

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

4. Richten Sie entsprechende Endpunkte ein, um die Debug-Berichte zu empfangen, die Sie generieren möchten. Debug-Berichte werden an drei separate Endpunkte im Berichtsursprung gesendet:

   • Endpunkt für Debug-Erfolgsberichte auf Ereignisebene: <reporting-origin>/.well-known/attribution-reporting/debug/report-event-attribution
   • Endpunkt für aggregierbare Debug-Erfolgsberichte: <reporting-origin>/.well-known/attribution-reporting/debug/report-aggregate-attribution
   • Endpunkt für ausführliche Debug-Berichte: <reporting-origin>/.well-known/attribution-reporting/debug/verbose

Generierte Erfolgs-Debug-Berichte sind identisch mit Attributionsberichten und enthalten die Quellen- und die Triggerseitigen Debug-Kennschlüssel in den Feldern "source_debug_key" bzw. "trigger_debug_key".

Weitere Informationen und Beispiele finden Sie unter:

• 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)