Letzte Updates
- Die Liste der anstehenden Änderungen und bekannten Probleme wurde aktualisiert.
- Einführung der flexiblen Konfiguration auf Ereignisebene als Brücke zur vollständigen flexiblen Konfiguration auf Ereignisebene
- Ab September 2023 müssen in
registerWebSource
,registerWebTrigger
,registerAppSource
undregisterAppTrigger
Strings für Felder verwendet werden, für die ein numerischer Wert erwartet wird (z. B.priority
,source_event_id
,debug_key
,trigger_data
unddeduplication_key
). - Im 4. Quartal 2023 wird die Android Attribution Reporting API um Google Cloud-Unterstützung erweitert, damit Zusammenfassungsberichte mit dem Aggregation Service in Google Cloud erstellt werden können. Näheres dazu finden Sie hier. Weitere Informationen zum Einrichten des Aggregationsdienstes mit Google Cloud finden Sie in der Bereitstellungsanleitung.
- Neue datenschutzfreundliche Ratenlimits für die Anzahl der eindeutigen Ziele.
- Im 1. Quartal 2024 werden die Funktionen für Triggerfilter für Lookback-Fenster aktualisiert. Weitere Informationen finden Sie in der entsprechenden Anmerkung.
Übersicht
Heutzutage werden Lösungen für dienstleisterübergreifende Nutzer-IDs wie die Werbe-ID häufig für mobile Attributions- und Analyselösungen verwendet. Die Attribution Reporting API wurde entwickelt, um den Datenschutz für Nutzer zu verbessern. Dabei wird die Abhängigkeit von dienstleisterübergreifenden Nutzerkennungen entfernt und gleichzeitig werden wichtige Anwendungsfälle für die Attributions- und Conversion-Analyse in Apps und im Web unterstützt.
Diese API verfügt über die folgenden strukturellen Mechanismen, die ein Framework zur Verbesserung des Datenschutzes bieten, das in späteren Abschnitten auf dieser Seite ausführlicher beschrieben wird:
- Begrenzt die Anzahl der für Berichte auf Ereignisebene verfügbaren Bits.
- Conversion-Daten mit höherer Genauigkeit werden nur in aggregierbaren Berichten aktiviert.
- Ratenbegrenzungen für verfügbare Trigger (Conversions) und die Anzahl der Anzeigentechnologien, die einer einzelnen Attributionsquelle zugeordnet werden können, werden eingeführt.
- Verschiedene Verfahren zum Hinzufügen von Rauschen
Die vorherigen Mechanismen schränken die Möglichkeit ein, die Nutzeridentität über zwei verschiedene Anwendungen oder Domains hinweg zu verknüpfen.
Die Attribution Reporting API unterstützt die folgenden Anwendungsfälle:
- Conversion-Berichte:Werbetreibende erhalten Informationen zur Anzahl der Conversions (Trigger) und Conversion-Werte (Trigger) für verschiedene Dimensionen, z. B. nach Kampagne, Anzeigengruppe und Anzeige. So können Werbetreibende die Leistung ihrer Kampagnen besser analysieren.
- Optimierung:Sie können Berichte auf Ereignisebene bereitstellen, mit denen sich die Werbeausgaben optimieren lassen. Dazu werden Attributionsdaten pro Impression bereitgestellt, die zum Trainieren von ML-Modellen verwendet werden können.
- Erkennung ungültiger Aktivitäten: Sie stellen Berichte zur Verfügung, die bei der Erkennung und Analyse ungültiger Zugriffe und Anzeigenbetrugs verwendet werden können.
Die Attribution Reporting API funktioniert im Groben so, wie in den folgenden Abschnitten dieses Dokuments genauer beschrieben:
- Das AdTech-Unternehmen führt einen Registrierungsprozess durch, um die Attribution Reporting API zu verwenden.
- Das AdTech-Unternehmen registriert Attributionsquellen – Anzeigenklicks oder -aufrufe – mit der Attribution Reporting API.
- Die Anzeigentechnologie registriert Trigger – Nutzer-Conversions in der App oder auf der Website des Werbetreibenden – mit der Attribution Reporting API.
- Die Attribution Reporting API gleicht Trigger mit Attributionsquellen – einer Conversion-Attribution – ab und mindestens ein Trigger wird über Berichte auf Ereignisebene und aggregierbare Berichte an Anzeigentechnologie-Anbieter gesendet.
Zugriff auf Attribution Reporting APIs erhalten
Anzeigentechnologie-Plattformen müssen sich registrieren, um auf die Attribution Reporting APIs zugreifen zu können. Weitere Informationen finden Sie unter Privacy Sandbox-Konto registrieren.
Attributionsquelle registrieren (Klick- oder Aufrufmessung)
In der Attribution Reporting API werden Anzeigenklicks und -aufrufe als Attributionsquellen bezeichnet. Rufen Sie registerSource()
auf, um einen Anzeigenklick oder einen Anzeigenaufruf zu registrieren. Für diese API sind die folgenden Parameter erforderlich:
- URI der Attributionsquelle:Die Plattform sendet eine Anfrage an diesen URI, um Metadaten abzurufen, die mit der Attributionsquelle verknüpft sind.
- Eingabeereignis: Entweder ein
InputEvent
-Objekt (für ein Klickereignis) odernull
(für ein Aufrufereignis).
Wenn die API eine Anfrage an den URI der Attributionsquelle sendet, sollte die Anzeigentechnologie mit den Metadaten der Attributionsquelle in einem neuen HTTP-Header Attribution-Reporting-Register-Source
mit den folgenden Feldern antworten:
- Ereignis-ID der Quelle: Dieser Wert steht für die Daten auf Ereignisebene, die mit dieser Attributionsquelle (Anzeigenklick oder -aufruf) verknüpft sind. Muss eine 64-Bit-nicht signierte Ganzzahl sein, die als String formatiert ist.
- Ziel: Ein Ursprung mit dem eTLD+1 oder App-Paketnamen, an dem das Triggerereignis auftritt.
- Ablaufzeit (optional): Ablaufzeit in Sekunden, nach der die Quelle vom Gerät gelöscht werden soll. Der Standardwert ist 30 Tage. Der Mindestwert ist 1 Tag und der Höchstwert 30 Tage. Dieser Wert wird auf den nächsten Tag aufgerundet. Kann als vorzeichenlose 64-Bit-Ganzzahl oder als String formatiert werden.
- Zeitraum für Ereignisberichte (optional): Dauer in Sekunden nach der Registrierung der Quelle, in der Ereignisberichte für diese Quelle erstellt werden können. Wenn das Fenster für Ereignisberichte abgelaufen ist, aber das Ablaufdatum noch nicht erreicht wurde, kann ein Trigger weiterhin mit einer Quelle abgeglichen werden. Für diesen Trigger wird jedoch kein Ereignisbericht gesendet. Darf nicht größer als „Expiry“ sein. Kann als 64-Bit-Ganzzahl oder String ohne Vorzeichen formatiert werden.
- Aggregierbares Berichtsfenster (optional): Dauer in Sekunden nach der Quellenregistrierung, in der aggregierte Berichte für diese Quelle erstellt werden können. Darf nicht größer als das Ablaufdatum sein. Kann als 64-Bit-Ganzzahl ohne Vorzeichen oder als String formatiert werden.
- Priorität der Quelle (optional): Hiermit wird ausgewählt, welcher Attributionsquelle ein bestimmter Trigger zugeordnet werden soll, falls dem Trigger mehrere Attributionsquellen zugeordnet werden können. Muss eine vorzeichenbehaftete 64-Bit-Ganzzahl sein, die als String formatiert ist.
Wenn ein Trigger empfangen wird, sucht die API die übereinstimmende Attributionsquelle mit der höchsten Priorität und generiert einen Bericht. Für jede AdTech-Plattform kann eine eigene Priorisierungsstrategie definiert werden. Weitere Informationen dazu, wie sich die Priorität auf die Attribution auswirkt, finden Sie im Abschnitt Beispiel für die Priorisierung.
Höhere Werte bedeuten eine höhere Priorität. - Attributionsfenster für Installationen und nach der Installation (optional): Wird verwendet, um die Attribution für Ereignisse nach der Installation zu bestimmen, die weiter unten auf dieser Seite beschrieben werden.
- Daten filtern (optional): Damit können einige Trigger selektiv herausgefiltert und so effektiv ignoriert werden. Weitere Informationen finden Sie im Abschnitt Triggerfilter auf dieser Seite.
- Aggregationsschlüssel (optional): Geben Sie die Segmentierung an, die für aggregierbare Berichte verwendet werden soll.
Optional kann die Metadatenantwort der Attributionsquelle zusätzliche Daten im Header der Weiterleitungen der Attributionsberichte enthalten. Die Daten enthalten Weiterleitungs-URLs, über die mehrere Anzeigentechnologien eine Anfrage registrieren können.
Der Entwicklerleitfaden enthält Beispiele, die zeigen, wie die Registrierung von Quellen akzeptiert wird.
Die folgenden Schritte zeigen einen Beispiel-Workflow:
Das AdTech-SDK ruft die API auf, um die Registrierung der Attributionsquelle zu starten, und gibt einen URI für den API-Aufruf an:
registerSource( Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"), myClickEvent);
Die API sendet mit einem der folgenden Header eine Anfrage an
https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA
:<!-- For click events --> Attribution-Reporting-Source-Info: navigation <!-- For view events --> Attribution-Reporting-Source-Info: event
Der HTTPS-Server dieser Anzeigentechnologie antwortet mit Headern, die Folgendes enthalten:
Attribution-Reporting-Register-Source: { "destination": "android-app://com.advertiser.example", "source_event_id": "234", "expiry": "60000", "priority": "5" } Attribution-Reporting-Redirect: https://adtechpartner1.example?their_ad_click_id=567 Attribution-Reporting-Redirect: https://adtechpartner2.example?their_ad_click_id=890
Die API sendet eine Anfrage an jede in
Attribution-Reporting-Redirect
angegebene URL. In diesem Beispiel werden zwei URLs von Anzeigentechnologie-Partnern angegeben. Die API stellt also eine Anfrage anhttps://adtechpartner1.example?their_ad_click_id=567
und eine weitere Anfrage anhttps://adtechpartner2.example?their_ad_click_id=890
.Der HTTPS-Server dieser Anzeigentechnologie antwortet mit Headern, die Folgendes enthalten:
Attribution-Reporting-Register-Source: { "destination": "android-app://com.advertiser.example", "source_event_id": "789", "expiry": "120000", "priority": "2" }
Auf Grundlage der Anfragen in den vorherigen Schritten werden drei Attributionsquellen für die Navigation (Klick) registriert.
Attributionsquelle aus WebView registrieren
WebView unterstützt den Anwendungsfall, bei dem eine App eine Anzeige in einem WebView rendert. Dies wird von WebView direkt ausgeführt, indem registerSource()
als Hintergrundanfrage aufgerufen wird. Bei diesem Aufruf wird die Attributionsquelle der App und nicht dem Ursprung auf oberster Ebene zugeordnet. Die Registrierung von Quellen von eingebetteten Webinhalten in einem Browserkontext wird ebenfalls unterstützt. Sowohl API-Aufrufer als auch Apps müssen die Einstellungen dafür anpassen. Eine Anleitung für API-Aufrufer finden Sie unter Attributionsquelle und Trigger aus WebView registrieren. Eine Anleitung für Apps finden Sie unter Attributionsquelle und Triggerregistrierung von WebView.
Da Anzeigentechnologie-Anbieter für Web und WebView gemeinsamen Code verwenden, folgt WebView HTTP 302-Weiterleitungen und leitet die gültigen Registrierungen an die Plattform weiter. Wir planen nicht, den Attribution-Reporting-Redirect
-Header für dieses Szenario zu unterstützen. Wenden Sie sich jedoch an uns, wenn Sie einen davon betroffenen Anwendungsfall haben.
Trigger (Conversion) registrieren
Anbieter von Anzeigentechnologien können mit der registerTrigger()
-Methode Trigger registrieren, also Conversions wie Installationen oder Ereignisse nach der Installation.
Die Methode registerTrigger()
erwartet den Parameter Trigger-URI. Die API sendet eine Anfrage an diesen URI, um Metadaten abzurufen, die mit dem Trigger verknüpft sind.
Die API folgt Weiterleitungen. Die Antwort des AdTech-Servers sollte einen HTTP-Header mit dem Namen Attribution-Reporting-Register-Trigger
enthalten, der Informationen zu einem oder mehreren registrierten Triggern darstellt. Der Inhalt des Headers sollte JSON-codiert sein und die folgenden Felder enthalten:
- Triggerdaten:Daten zum Identifizieren des Triggerereignisses (3 Bit für Klicks, 1 Bit für Aufrufe). Muss eine vorzeichenbehaftete 64‑Bit-Ganzzahl sein, die als String formatiert ist.
- Triggerpriorität (optional): Die Priorität dieses Trigger im Vergleich zu anderen Triggern für dieselbe Attributionsquelle. Muss eine vorzeichenbehaftete 64-Bit-Ganzzahl sein, die als String formatiert ist. Weitere Informationen dazu, wie sich die Priorität auf die Berichte auswirkt, finden Sie im Abschnitt Priorisierung.
- Deduplizierungsschlüssel (optional): Wird verwendet, um Fälle zu identifizieren, in denen derselbe Trigger von derselben AdTech-Plattform mehrmals für dieselbe Attributionsquelle registriert wird. Muss eine vorzeichenbehaftete 64-Bit-Ganzzahl sein, die als String formatiert ist.
- Aggregationsschlüssel (optional): Eine Liste von Wörterbüchern, in denen Aggregationsschlüssel angegeben sind und in welchen aggregierten Berichten der Wert aggregiert werden soll.
- Aggregationswerte (optional): Eine Liste von Werten, die zu jedem Schlüssel beitragen.
- Filter (optional): Damit lassen sich Trigger oder Triggerdaten selektiv filtern. Weitere Informationen finden Sie auf dieser Seite im Abschnitt Triggerfilter.
Optional kann die Antwort des AdTech-Servers zusätzliche Daten im Header Attribution Reporting Redirects enthalten. Die Daten enthalten Weiterleitungs-URLs, über die mehrere Anzeigentechnologien eine Anfrage registrieren können.
Mehrere Anzeigentechnologie-Anbieter können dasselbe Triggerereignis registrieren, indem sie entweder Weiterleitungen im Feld Attribution-Reporting-Redirect
oder mehrere Aufrufe der Methode registerTrigger()
verwenden. Wir empfehlen die Verwendung des Felds Deduplizierungsschlüssel, um zu vermeiden, dass Berichte doppelte Trigger enthalten, wenn dieselbe Anzeigentechnologie mehrere Antworten für dasselbe Triggerereignis liefert. Weitere Informationen zur Verwendung eines Deduplizierungsschlüssels
Der Entwicklerleitfaden enthält Beispiele, die zeigen, wie die Triggerregistrierung akzeptiert wird.
Die folgenden Schritte zeigen einen Beispielworkflow:
Das AdTech-SDK ruft die API auf, um die Triggerregistrierung mit einem vorab registrierten URI zu starten. Weitere Informationen finden Sie unter Privacy Sandbox-Konto registrieren.
registerTrigger( Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
Die API sendet eine Anfrage an
https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA
.Der HTTPS-Server dieser Anzeigentechnologie antwortet mit Headern, die Folgendes enthalten:
Attribution-Reporting-Register-Trigger: { "event_trigger_data": [{ "trigger_data": "1122", // This returns 010 for click-through conversions (CTCs) and 0 for // view-through conversions (VTCs) in reports "priority": "3", "deduplication_key": "3344" }], } Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
Die API sendet eine Anfrage an jede in
Attribution-Reporting-Redirect
angegebene URL. In diesem Beispiel wird nur eine URL angegeben. Die API stellt also eine Anfrage anhttps://adtechpartner.example?app_install=567
.Der HTTPS-Server dieser Anzeigentechnologie antwortet mit Headern, die Folgendes enthalten:
Attribution-Reporting-Register-Trigger: { "event_trigger_data":[{ "trigger_data": "5566", "priority": "3", "deduplication_key": "3344" }] }
Basierend auf den Anfragen in den vorherigen Schritten werden zwei Trigger registriert.
Attributionsfunktionen
In den folgenden Abschnitten wird erläutert, wie die Attribution Reporting API Conversion-Trigger mit Attributionsquellen abgleicht.
Algorithmus für die priorisierte Attribution nach Quelle angewendet
Die Attribution Reporting API verwendet einen quellenpriorisierten Attributionsalgorithmus, um einen Trigger (Conversion) einer Attributionsquelle zuzuordnen.
Mit Prioritätsparametern können Sie die Attribution von Triggern zu Quellen anpassen:
- Trigger können bestimmten Anzeigenereignissen Vorrang vor anderen geben. Sie können beispielsweise den Schwerpunkt auf Klicks statt auf Aufrufe legen oder sich auf Ereignisse aus bestimmten Kampagnen konzentrieren.
- Sie können die Attributionsquelle und den Trigger so konfigurieren, dass Sie beim Erreichen von Ratenbegrenzungen mit größerer Wahrscheinlichkeit die Berichte erhalten, die für Sie wichtiger sind. So lässt sich z. B. festlegen, dass gebotsfähige oder hochwertige Conversions mit größerer Wahrscheinlichkeit in diesen Berichten zu sehen sind.
Wenn mehrere Anzeigentechnologien eine Attributionsquelle registrieren, wie weiter unten auf dieser Seite beschrieben, erfolgt die Attribution für jede Anzeigentechnologie unabhängig. Für jede Anzeigentechnologie wird die Attributionsquelle mit der höchsten Priorität dem Triggerereignis zugeordnet. Wenn es mehrere Attributionsquellen mit derselben Priorität gibt, wählt die API die zuletzt registrierte Attributionsquelle aus. Alle anderen Attributionsquellen, die nicht ausgewählt wurden, werden verworfen und können nicht mehr für eine zukünftige Triggerattribution verwendet werden.
Triggerfilter
Die Registrierung von Quellen und Triggern umfasst zusätzliche optionale Funktionen, mit denen Sie Folgendes tun können:
- Einige Trigger werden selektiv gefiltert und ignoriert.
- Wählen Sie Triggerdaten für Berichte auf Ereignisebene basierend auf Quelldaten aus.
- Sie können einen Trigger aus Berichten auf Ereignisebene ausschließen.
Um Trigger selektiv zu filtern, kann die Anzeigentechnologie bei der Registrierung von Quellen und Triggern Filterdaten aus Schlüsseln und Werten angeben. Wenn für die Quelle und den Trigger derselbe Schlüssel angegeben ist, wird der Trigger ignoriert, wenn die Überschneidung leer ist. In einer Quelle kann beispielsweise "product": ["1234"]
angegeben werden, wobei product
der Filterschlüssel und 1234
der Wert ist. Wenn der Triggerfilter auf "product": ["1111"]
gesetzt ist, wird der Trigger ignoriert. Wenn kein Triggerfilterschlüssel vorhanden ist, der mit product
übereinstimmt, werden die Filter ignoriert.
Ein weiteres Szenario, in dem AdTech-Plattformen Trigger selektiv filtern möchten, ist das Erzwingen eines kürzeren Ablauffensters. Bei der Trigger-Registrierung kann ein Anzeigentechnologie-Anbieter ein Lookback-Window in Sekunden angeben, ab dem die Conversion erfolgt ist. Ein Lookback-Window von 7 Tagen wird beispielsweise so definiert: "_lookback_window":
604800 // 7d
Um zu entscheiden, ob ein Filter übereinstimmt, prüft die API zuerst das Lookback-Window. Falls verfügbar, muss die Dauer seit der Registrierung der Quelle kleiner oder gleich der Dauer des Lookback-Windows sein.
AdTech-Plattformen können außerdem Triggerdaten basierend auf Quellereignisdaten auswählen. Beispiel: source_type
wird von der API automatisch als navigation
oder event
generiert. Bei der Triggerregistrierung kann trigger_data
als Wert für "source_type": ["navigation"]
und als anderer Wert für "source_type": ["event"]
festgelegt werden.
Auslöser werden aus Berichten auf Ereignisebene ausgeschlossen, wenn eine der folgenden Bedingungen zutrifft:
- Es ist kein
trigger_data
angegeben. - Für Quelle und Trigger ist derselbe Filterschlüssel angegeben, die Werte stimmen jedoch nicht überein. In diesem Fall wird der Trigger sowohl für Berichte auf Ereignisebene als auch für aggregierbare Berichte ignoriert.
Attribution nach der Installation
In einigen Fällen müssen Trigger nach der Installation derselben Attributionsquelle zugeordnet werden, die zur Installation geführt hat, auch wenn es andere zulässige Attributionsquellen gibt, die erst vor Kurzem erfolgt sind.
Die API kann diesen Anwendungsfall unterstützen, indem Anbieter von Anzeigentechnologien einen Attributionszeitraum nach der Installation festlegen können:
- Geben Sie beim Registrieren einer Attributionsquelle ein Zeitfenster für die Attribution von Installationen an, in dem Installationen zu erwarten sind (in der Regel 2–7 Tage, zulässig sind 1 bis 30 Tage). Geben Sie dieses Zeitfenster in Sekunden an.
- Wenn Sie eine Attributionsquelle registrieren, geben Sie nach der Installation ein Exklusivitätsfenster für die Attribution nach der Installation an, in dem alle Trigger nach der Installation der Attributionsquelle zugeordnet werden sollen, die zur Installation geführt hat (in der Regel 7 bis 30 Tage, zulässiger Bereich zwischen 0 und 30 Tagen). Geben Sie dieses Zeitfenster als Anzahl von Sekunden an.
- Die Attribution Reporting API prüft, wann eine App-Installation erfolgt, und ordnet die Installation intern der quellenpriorisierten Attributionsquelle zu. Die Installation wird jedoch nicht an Anzeigentechnologie-Anbieter gesendet und nicht auf die jeweiligen Ratenbegrenzungen der Plattformen angerechnet.
- Die Validierung von App-Installationen ist für jede heruntergeladene App verfügbar.
- Alle zukünftigen Trigger, die innerhalb des Attributionszeitraums nach der Installation erfolgen, werden derselben Attributionsquelle wie die validierte Installation zugeordnet, sofern diese Attributionsquelle infrage kommt.
Zukünftig wird es eventuell darum gehen, das Design zu erweitern, damit erweiterte Attributionsmodelle unterstützt werden.
In der folgenden Tabelle sehen Sie ein Beispiel dafür, wie Anzeigentechnologie die Attribution nach der Installation verwenden können. Angenommen, alle Attributionsquellen und ‑trigger werden vom selben AdTech-Netzwerk registriert und alle Prioritäten sind gleich.
Ereignis | Tag, an dem das Ereignis eintritt | Hinweise |
---|---|---|
Klick 1 | 1 | install_attribution_window ist auf 172800 (2 Tage) und post_install_exclusivity_window auf 864000 (10 Tage) festgelegt. |
Verifizierte Installation | 2 | Die API ordnet verifizierte Installationen intern zu, diese Installationen gelten jedoch nicht als Trigger. Daher werden derzeit keine Berichte gesendet. |
Trigger 1 (erstes Öffnen) | 2 | Erster Trigger, der von der Anzeigentechnologie registriert wurde. In diesem Beispiel steht er für ein erstes Öffnen, kann aber auch einen beliebigen Triggertyp darstellen. Klick 1 zugeordnet (entspricht der Attribution der bestätigten Installation). |
Klick 2 | 4 | Für install_attribution_window und post_install_exclusivity_window werden dieselben Werte wie für Klick 1 verwendet. |
Trigger 2 (nach der Installation) | 5 | Zweiter Trigger, der von der Anzeigentechnologie registriert wird. In diesem Beispiel stellt er eine Conversion nach der Installation dar, z. B. einen Kauf. Klick 1 zugeordnet (entspricht der Attribution der bestätigten Installation). Klick 2 wird verworfen und kann nicht für die zukünftige Attribution verwendet werden. |
Die folgende Liste enthält einige zusätzliche Hinweise zur Attribution nach der Installation:
- Wenn die bestätigte Installation nicht innerhalb der von
install_attribution_window
angegebenen Anzahl von Tagen erfolgt, wird die Attribution nach der Installation nicht angewendet. - Verifizierte Installationen werden nicht von Anzeigentechnologien registriert und nicht in Berichten gesendet. Sie werden nicht auf die Ratenbegrenzungen eines Anzeigentechnologie-Anbieters angerechnet. Bestätigte Installationen werden nur verwendet, um die Attributionsquelle zu identifizieren, der die Installation zugeordnet wird.
- Im Beispiel der vorherigen Tabelle stellen Trigger 1 und Trigger 2 eine Conversion vom Typ „Erstes Öffnen“ und „Conversion nach der Installation“ dar. Auf Anzeigentechnologie-Plattformen kann jedoch jede Art von Trigger registriert werden. Der erste Trigger muss also kein erster offener Trigger sein.
- Wenn nach Ablauf des
post_install_exclusivity_window
weitere Trigger registriert werden, kommt Klick 1 weiterhin für die Attribution infrage, sofern er nicht abgelaufen ist und die Ratenbegrenzungen noch nicht erreicht hat.- Klick 1 kann weiterhin verloren gehen oder verworfen werden, wenn eine Attributionsquelle mit höherer Priorität registriert ist.
- Wenn die App des Werbetreibenden deinstalliert und wieder installiert wird, wird die Neuinstallation als neue bestätigte Installation gezählt.
- Wenn Klick 1 stattdessen ein Aufrufereignis war, werden ihm weiterhin sowohl der Trigger "Erstes Öffnen" als auch der Trigger nach der Installation zugeordnet. Die API beschränkt die Attribution auf einen Trigger pro Ansicht, außer im Fall einer Attribution nach der Installation, bei der bis zu zwei Trigger pro Aufruf zulässig sind. Bei der Attribution nach der Installation erhält der Anzeigentechnologie-Anbieter unter Umständen zwei verschiedene Berichtsfenster (nach 2 Tagen oder nach Ablauf der Quelle).
Alle Kombinationen aus App- und webbasierten Triggerpfaden werden unterstützt
Mit der Attribution Reporting API können die folgenden Triggerpfade auf einem einzelnen Android-Gerät zugeordnet werden:
- App-to-app::Der Nutzer sieht eine Anzeige in einer App und führt dann entweder in dieser oder in einer anderen installierten App eine Conversion aus.
- App-zu-Web: Der Nutzer sieht eine Anzeige in einer App und führt dann in einem mobilen Browser oder einem In-App-Browser eine Conversion aus.
- Web-to-app::Der Nutzer sieht eine Anzeige in einem mobilen Browser oder App-Browser und führt dann in einer App eine Conversion aus.
- Web-zu-Web: Der Nutzer sieht sich eine Anzeige in einem mobilen Browser oder In-App-Browser an und führt dann entweder im selben Browser oder in einem anderen Browser auf demselben Gerät eine Conversion aus.
Wir erlauben Webbrowsern, neue Webfunktionen zu unterstützen, z. B. Funktionen, die der Attribution Reporting API der Privacy Sandbox für das Web ähneln. Diese Funktionen können die Android APIs aufrufen, um die App- und Web-Attribution zu ermöglichen.
Hier erfahren Sie, welche Änderungen an Anzeigentechnologien und Apps vorgenommen werden müssen, um Triggerpfade für die App- und Webanalyse zu unterstützen.
Mehrere Trigger für eine einzelne Attributionsquelle priorisieren
Eine einzelne Attributionsquelle kann zu mehreren Triggern führen. Ein Kaufvorgang kann beispielsweise einen Trigger für die App-Installation, einen oder mehrere Trigger vom Typ „In den Einkaufswagen“ und einen Trigger vom Typ „Kauf“ umfassen. Jeder Trigger wird gemäß dem Algorithmus für die quellenpriorisierte Attribution, der weiter unten auf dieser Seite beschrieben wird, einer oder mehreren Attributionsquellen zugeordnet.
Die Anzahl der Trigger, die einer einzelnen Attributionsquelle zugeordnet werden können, ist begrenzt. Weitere Informationen finden Sie weiter unten auf dieser Seite im Abschnitt Messdaten in Attributionsberichten aufrufen. Wenn mehrere Trigger diese Limits überschreiten, ist es sinnvoll, eine Priorisierungslogik einzuführen, um die wertvollsten Trigger zurückzugeben. Beispielsweise möchten die Entwickler einer Anzeigentechnologie eher „Kauf“-Trigger statt „In den Einkaufswagen“-Trigger erhalten.
Um diese Logik zu unterstützen, kann für den Trigger ein separates Prioritätsfeld festgelegt werden. Die Trigger mit der höchsten Priorität werden dann innerhalb eines bestimmten Berichtszeitraums ausgewählt, bevor Limits angewendet werden.
Registrierung von Attributionsquellen oder -triggern durch mehrere Anzeigentechnologien zulassen
Es ist üblich, dass mehrere Anzeigentechnologien Attributionsberichte erhalten, in der Regel zur netzwerkübergreifenden Deduplizierung. Mit der API können mehrere Anzeigentechnologie-Anbieter also dieselbe Attributionsquelle oder denselben Trigger registrieren. Ein AdTech-Anbieter muss sowohl Attributionsquellen als auch Trigger registrieren, um Postbacks von der API zu erhalten. Die Attribution erfolgt dann anhand der Attributionsquellen und Trigger, die der AdTech-Anbieter bei der API registriert hat.
Werbetreibende, die einen Drittanbieter mit der netzwerkübergreifenden Deduplizierung beauftragen möchten, können dies weiterhin mit einer Technik ähnlich der folgenden tun:
- Einrichten eines internen Servers zum Registrieren und Empfangen von Berichten von der API
- Einen vorhandenen Partner für mobile Messungen weiter verwenden
Attributionsquellen
Weiterleitungen auf Attributionsquellen werden von der registerSource()
-Methode unterstützt:
- Die Anzeigentechnologie, die die
registerSource()
-Methode aufruft, kann in ihrer Antwort ein zusätzlichesAttribution-Reporting-Redirect
-Feld angeben, das die Weiterleitungs-URLs der Anzeigentechnologie des Partners darstellt. - Die API ruft dann die Weiterleitungs-URLs auf, damit die Attributionsquelle von den Anzeigentechnologien des Partners registriert werden kann.
Im Feld Attribution-Reporting-Redirect
können mehrere URLs von Anzeigentechnologien von Partnern aufgeführt werden. Anbieter von Anzeigentechnologien von Partnern können kein eigenes Feld Attribution-Reporting-Redirect
angeben.
Über die API können auch verschiedene Anzeigentechnologien jeden registerSource()
-Aufruf verwenden.
Trigger
Bei der Triggerregistrierung werden Drittanbieter auf ähnliche Weise unterstützt: Anbieter von Anzeigentechnologien können entweder das zusätzliche Attribution-Reporting-Redirect
-Feld verwenden oder die registerTrigger()
-Methode aufrufen.
Wenn ein Werbetreibender mehrere Anzeigentechnologien verwendet, um dasselbe Triggerereignis zu erfassen, sollte ein Deduplizierungsschlüssel verwendet werden. Mit dem Deduplizierungsschlüssel lassen sich die wiederholten Berichte desselben Ereignisses, das von derselben Anzeigentechnologie-Plattform registriert wurde, eindeutig unterscheiden. Beispielsweise könnte ein Anzeigentechnologie-Anbieter festlegen, dass sein SDK die API direkt aufruft, um einen Trigger zu registrieren, und seine URL im Weiterleitungsfeld eines Aufrufs eines anderen Anzeigentechnologie-Anbieters angeben. Wenn kein Deduplizierungsschlüssel angegeben wird, werden doppelte Trigger möglicherweise als eindeutig an jede Anzeigentechnologie gemeldet.
Umgang mit doppelten Triggern
Ein Anzeigentechnologie-Anbieter registriert möglicherweise denselben Trigger mehrmals mit der API. Szenarien umfassen:
- Der Nutzer führt dieselbe Aktion (Trigger) mehrmals aus. Beispiel: Der Nutzer sieht sich dasselbe Produkt mehrmals im selben Berichtszeitraum an.
- Die App des Werbetreibenden verwendet mehrere SDKs für die Conversion-Analyse, die alle auf dieselbe Anzeigentechnologie verweisen. Beispiel: Die App des Werbetreibenden verwendet zwei Analysepartner, MMP 1 und MMP 2. Beide MMPs leiten zu AdTech #3 weiter. Wenn ein Trigger eintritt, wird er von beiden MMPs bei der Attribution Reporting API registriert. Die Anzeigentechnologie 3 erhält dann zwei separate Weiterleitungen – eine von MMP 1 und eine von MMP 2 – für denselben Trigger.
In diesen Fällen gibt es mehrere Möglichkeiten, Berichte auf Ereignisebene zu duplizierten Triggern zu unterdrücken, um das Risiko zu verringern, dass die Häufigkeitslimits für Berichte auf Ereignisebene überschritten werden. Es wird empfohlen, einen Deduplizierungsschlüssel zu verwenden.
Empfohlene Methode: Deduplizierungsschlüssel
Es wird empfohlen, dass die App eines Werbetreibenden einen eindeutigen Deduplizierungsschlüssel an alle Anzeigentechnologien oder SDKs sendet, die für die Conversion-Messung verwendet werden. Wenn eine Conversion erfolgt, übergibt die App einen Deduplizierungsschlüssel an die Anzeigentechnologien oder SDKs.
Diese Anzeigentechnologien oder SDKs geben den Deduplizierungsschlüssel dann mithilfe eines Parameters in den in Attribution-Reporting-Redirect
angegebenen URLs an Weiterleitungen weiter.
Anzeigentechnologie-Anbieter können entweder nur den ersten Trigger mit einem bestimmten Deduplizierungsschlüssel registrieren oder mehrere Trigger oder alle Trigger registrieren.
Anzeigentechnologie-Experten können beim Registrieren doppelter Trigger den deduplication_key
angeben.
Wenn ein Anzeigentechnologie-Anbieter mehrere Trigger mit demselben Deduplizierungsschlüssel und derselben zugeordneten Quelle registriert, wird nur der erste registrierte Trigger in Berichten auf Ereignisebene gesendet. Duplikate von Triggern werden weiterhin in verschlüsselten aggregierten Berichten gesendet.
Alternative Methode: Anbieter von Anzeigentechnologien einigen sich auf Triggertypen pro Werbetreibendem
In Situationen, in denen Anzeigentechnologie den Deduplizierungsschlüssel nicht verwenden möchten oder die App des Werbetreibenden keinen Deduplizierungsschlüssel übergeben kann, gibt es eine alternative Option. Alle Anzeigentechnologien, die Conversions für einen bestimmten Werbetreibenden erfassen, müssen zusammenarbeiten, um für jeden Werbetreibenden unterschiedliche Triggertypen zu definieren.
Anzeigentechnologien, die den Triggerregistrierungsaufruf initiieren, z. B. SDKs, fügen in Attribution-Reporting-Redirect
angegebenen URLs einen Parameter hinzu, z. B. duplicate_trigger_id
. Dieser duplicate_trigger_id
-Parameter kann Informationen wie den SDK-Namen und den Triggertyp für diesen Werbetreibenden enthalten. Anbieter von Anzeigentechnologien können dann einen Teil dieser doppelten Trigger in Berichte auf Ereignisebene aufnehmen.
Anzeigentechnologie-Anbieter können diese duplicate_trigger_id
auch in ihre Aggregationsschlüssel einbeziehen.
Beispiel für die netzwerkübergreifende Attribution
In diesem Abschnitt wird ein Beispiel beschrieben, in dem der Werbetreibende zwei Werbetechnologieplattformen für die Anzeigenbereitstellung (Werbetechnologie A und Werbetechnologie B) und einen Analysepartner (MMP) verwendet.
Zuerst müssen AdTech A, AdTech B und die MMP jeweils die Registrierung für die Attribution Reporting API abschließen. Weitere Informationen finden Sie unter Für ein Privacy Sandbox-Konto registrieren.
Die folgende Liste enthält eine Reihe hypothetischer Nutzeraktionen, die jeweils einen Tag auseinanderliegen, und wie die Attribution Reporting API diese Aktionen in Bezug auf AdTech A, Adtech B und MMP verarbeitet:
- Tag 1: Der Nutzer klickt auf eine Anzeige, die von Anzeigentechnologie A ausgeliefert wird.
Anzeigentechnologie A ruft
registerSource()
mit ihrem URI auf. Die API sendet eine Anfrage an den URI und der Klick wird mit den Metadaten aus der Serverantwort von Adtech A registriert.Die Anzeigentechnologie A enthält außerdem den URI der MMP im
Attribution-Reporting-Redirect
-Header. Die API sendet eine Anfrage an den MMP-URI und der Klick wird mit den Metadaten aus der Antwort des MMP-Servers registriert.- Tag 2: Der Nutzer klickt auf eine von AdTech B ausgelieferte Anzeige
AdTech B ruft
registerSource()
mit seinem URI auf. Die API sendet eine Anfrage an den URI und der Klick wird mit den Metadaten aus der Serverantwort von Ad Tech B registriert.Wie Anbieter A hat auch Anbieter B den URI der MMP in den
Attribution-Reporting-Redirect
-Header aufgenommen. Die API sendet eine Anfrage an den MMP-URI und der Klick wird mit den Metadaten aus der Antwort des MMP-Servers registriert.- Tag 3: Der Nutzer sieht sich eine Anzeige an, die von Ad Tech A ausgeliefert wird.
Die API reagiert wie am ersten Tag, mit der Ausnahme, dass eine Datenansicht für die Anzeigentechnologie A und die MMP registriert ist.
- Tag 4: Der Nutzer installiert die App, die den MMP für die Conversion-Analyse verwendet.
MMP ruft
registerTrigger()
mit dem entsprechenden URI auf. Die API sendet eine Anfrage an die URL und die Conversion wird mit den Metadaten aus der Serverantwort der MMP registriert.MMP enthält außerdem die URIs für Anzeigentechnologie A und Anzeigentechnologie B im
Attribution-Reporting-Redirect
-Header. Die API sendet Anfragen an die Server von Ad Tech A und Ad Tech B. Die Conversion wird dann entsprechend mit den Metadaten aus den Serverantworten registriert.
Das folgende Diagramm veranschaulicht den in der vorherigen Liste beschriebenen Prozess:
So funktioniert die Attribution:
- Die Anzeigentechnologie A setzt die Priorität von Klicks höher als die von Aufrufen und erhält daher die Installation, die dem Klick am ersten Tag zugeordnet wird.
- Für Anzeigentechnologie B wird die Installation an Tag 2 zugeordnet.
- MMP legt die Priorität von Klicks höher als die von Aufrufen fest und die Installation wird dem Klick an Tag 2 zugeordnet. Der Klick an Tag 2 hat die höchste Priorität, das letzte Anzeigenereignis.
Netzwerkübergreifende Attribution ohne Weiterleitungen
Wir empfehlen die Verwendung von Weiterleitungen, damit mehrere Anzeigentechnologien Attributionsquellen und ‑trigger registrieren können. Es kann jedoch Fälle geben, in denen Weiterleitungen nicht möglich sind. In diesem Abschnitt wird beschrieben, wie Sie die netzwerkübergreifende Attribution ohne Weiterleitungen unterstützen.
Gesamtfluss
- Bei der Quellenregistrierung gibt das ausliefernde Anzeigentechnologie-Netzwerk seine Quellenaggregationsschlüssel frei.
- Bei der Triggerregistrierung wählt der Werbetreibende oder Analysepartner aus, welche wichtigen datenquellenseitigen Informationen verwendet werden sollen, und gibt die Attributionskonfiguration an.
- Die Attribution basiert auf der Attributionskonfiguration, freigegebenen Schlüsseln und allen Quellen, die von diesem Werbetreibenden oder Analysepartner tatsächlich registriert wurden (z. B. von einem anderen AdTech-Netzwerk für die Anzeigenbereitstellung, das Weiterleitungen aktiviert hat).
- Wenn der Trigger einer Quelle von einer Anzeigentechnologie zugeordnet wird, die keine Weiterleitung hat, kann der Werbetreibende oder Partner für Messungen einen aggregierten Bericht erhalten, in dem die in Schritt 2 definierten Quelle und die Schlüsselelemente des Triggers kombiniert werden.
Quellenregistrierung
Bei der Quellenregistrierung kann das bereitstellende Anzeigentechnologie-Netzwerk auswählen, ob es seine Quellenaggregationsschlüssel oder einen Teil seiner Quellenaggregationsschlüssel freigeben möchte, anstatt eine Weiterleitung durchzuführen. Die Technologie zur Anzeigenbereitstellung muss diese Quellschlüssel nicht in eigenen aggregierten Berichten verwenden und kann sie bei Bedarf nur im Namen des Werbetreibenden oder Partners für Messungen deklarieren.
Gemeinsame Aggregationsschlüssel stehen jeder Anzeigentechnologie zur Verfügung, die einen Trigger für denselben Werbetreibenden registriert. Es liegt jedoch an der Auslieferungstechnologie und der Anzeigentechnologie für die Triggermessung, die benötigten Arten von Aggregationsschlüsseln, ihre Namen und die Decodierung der Schlüssel in lesbare Dimensionen zu bestimmen.
Registrierung auslösen
Bei der Triggerregistrierung wählt die Messtechnologie aus, welche Quellschlüsselteile auf die einzelnen Triggerschlüsselteile angewendet werden sollen, einschließlich derjenigen, die von Technologien für die Anzeigenbereitstellung freigegeben werden.
Außerdem muss die AdTech-Plattform für die Analyse die Abfolge der Attributionslogik mit einem neuen API-Aufruf für die Attributionskonfiguration angeben. In dieser Konfiguration kann die Anzeigentechnologie die Quellenpriorität, das Ablaufdatum und Filter für Quellen angeben, die nicht sichtbar waren (z. B. Quellen ohne Weiterleitung).
Attribution
Die Attribution Reporting API führt eine nach Quelle priorisierte Attribution nach dem letzten Touchpoint für die Messtechnologie durch, basierend auf der Attributionskonfiguration, freigegebenen Schlüsseln und allen registrierten Quellen. Beispiel:
- Der Nutzer hat auf die Anzeigen der Anzeigentechnologien A, B, C und D geklickt. Der Nutzer hat dann die App des Werbetreibenden installiert, in der ein Anbieter von Analysetechnologien für Werbung (MMP) verwendet wird.
- Anzeigentechnologie A leitet ihre Quellen an den MMP weiter.
- Die Anzeigentechnologien B und C führen nicht weiter, teilen aber ihre Aggregationsschlüssel.
- Die Anzeigentechnologie D leitet die Schlüssel nicht weiter und gibt auch keine Aggregationsschlüssel frei.
Der MMP registriert eine Quelle von Anzeigentechnologie A und definiert eine Attributionskonfiguration, die die Anzeigentechnologie B und die Anzeigentechnologie D umfasst.
Die Attribution für die MMP umfasst jetzt:
- Anzeigentechnologie A, da der MMP eine Quelle über die Weiterleitung dieser Anzeigentechnologie registriert hat.
- Anzeigentechnologie B, da Anzeigentechnologie B Schlüssel freigegeben und vom MMP in die Attributionskonfiguration aufgenommen wurde.
Die Attribution für das MMP umfasst Folgendes nicht:
- Anzeigentechnologie C, da sie vom MMP nicht in der Attributionskonfiguration berücksichtigt wurde.
- Anbieter D, da er weder weiterleitet noch Aggregationsschlüssel freigibt.
Debugging
Zur Unterstützung der Fehlerbehebung bei der netzwerkübergreifenden Attribution ohne Weiterleitungen steht Anbietern von Anzeigentechnologien bei der Quellenregistrierung ein zusätzliches Feld (shared_debug_key
) zur Verfügung. Wenn er für die ursprüngliche Quellregistrierung festgelegt wurde, wird er bei der Registrierung des Triggers für die netzwerkübergreifende Attribution ohne Weiterleitungen auch für die entsprechende abgeleitete Quelle als debug_key
festgelegt. Dieser Schlüssel zur Fehlerbehebung wird in Ereignis- und aggregierten Berichten als source_debug_key
angehängt.
Diese Debugging-Funktion wird nur in den folgenden Szenarien für die netzwerkübergreifende Attribution ohne Weiterleitungen unterstützt:
- App-zu-App-Analyse, bei der die AdId zulässig ist
- App-zu-Web-Analyse, bei der die Anzeigen-ID zulässig ist und sowohl in der App-Quelle als auch im Webtrigger übereinstimmt
- Web-zu-Web-Analyse (in derselben Browser-App), wenn
ar_debug
sowohl in der Quelle als auch im Trigger vorhanden ist
Schlüsselerkennung für netzwerkübergreifende Attribution ohne Weiterleitungen
Mit der Schlüsselerkennung soll optimiert werden, wie AdTechs (in der Regel MMPs) ihre Attributionskonfiguration für die netzwerkübergreifende Attribution implementieren, wenn mindestens ein Anzeigentechnologie-Anbieter gemeinsame Aggregationsschlüssel verwendet (siehe oben unter Netzwerkübergreifende Attribution ohne Weiterleitungen).
Wenn eine MMP den Aggregationsdienst abfragt, um Zusammenfassungsberichte für Kampagnen zu generieren, die abgeleitete Quellen enthalten, muss die MMP die Liste der möglichen Schlüssel als Eingabe für den Aggregationsjob angeben. In einigen Fällen kann die Liste potenzieller Aggregationsschlüssel der Quelle sehr groß oder unbekannt sein. Große Listen möglicher Schlüssel sind schwierig nachzuverfolgen. Außerdem sind sie wahrscheinlich ziemlich komplex und kostspielig in der Verarbeitung. Betrachten Sie hierzu folgende Beispiele:
- Die Liste aller möglichen Schlüssel ist lang:
- Ein Anzeigennetzwerk führt eine komplexe Initiative zur Nutzergewinnung durch, die 20 Kampagnen mit jeweils 10 Anzeigengruppen umfasst. Jede Anzeigengruppe enthält 5 Creatives, die jede Woche basierend auf der Leistung aktualisiert werden.
- Die Liste aller möglichen Schlüssel ist unbekannt:
- Über ein auslieferndes Werbenetzwerk werden Anzeigen in vielen mobilen Apps ausgeliefert, in denen zum Start der Kampagne die vollständige Liste der App-IDs der Publisher noch nicht bekannt ist.
- Ein Werbetreibender arbeitet mit mehreren Werbenetzwerken, die bei der Quellenregistrierung nicht zur MMP weiterleiten. Jedes Werbenetzwerk hat eine andere Schlüsselstruktur und andere Werte, die möglicherweise nicht vorab mit der MMP geteilt werden.
Durch die Einführung der Schlüsselerkennung:
- Für den Aggregationsdienst ist keine vollständige Aufzählung möglicher Aggregationsschlüssel mehr erforderlich.
- Anstatt die vollständige Liste der möglichen Schlüssel angeben zu müssen, kann ein MMP einen leeren (oder teilweise leeren) Schlüsselsatz erstellen und einen Grenzwert festlegen, sodass nur (nicht vorab deklarierte) Schlüssel mit Werten, die den Grenzwert überschreiten, in die Ausgabe aufgenommen werden.
- MMP erhält einen Zusammenfassungsbericht, der Rauschwerte für Schlüssel enthält, deren Werte über dem festgelegten Grenzwert liegen. Der Bericht kann auch Schlüssel enthalten, denen keine echten Nutzerbeiträge zugeordnet sind und die nur verrauscht sind.
- Das MMP verwendet das Feld
x_network_bit_mapping
bei der Triggerregistrierung, um zu ermitteln, welche Anzeigentechnologie welchem Schlüssel entspricht. - MMP kann sich dann an den entsprechenden Anzeigentechnologie-Anbieter wenden, um die Werte im Quellschlüssel zu ermitteln.
Zusammenfassend lässt sich sagen, dass MMPs durch die Schlüsselerkennung Aggregationsschlüssel abrufen können, ohne sie im Voraus zu kennen, und die Verarbeitung einer großen Menge von Quellschlüsseln auf Kosten von zusätzlichem Rauschen vermeiden.
Daisy-Chain-Weiterleitungen
Wenn ein Anbieter von Anzeigentechnologien mehrere Attribution-Reporting-Redirect
-Header in einer HTTPS-Serverantwort für die Registrierung einer Quelle oder eines Triggers angibt, kann er mit der Attribution Reporting API mehrere Registrierungen von Quellen und Triggern mit einem einzigen Registration API-Aufruf ausführen.
In der Serverantwort kann die Anzeigentechnologie auch einen einzelnen Location
-Header (302-Weiterleitung) mit einer URL enthalten, der wiederum zu einer weiteren Registrierung führt, bis zu einem festgelegten Limit.
Beide Arten von Headern sind optional. Wenn keine Weiterleitungen erforderlich sind, können auch keine angegeben werden. Es können entweder ein oder beide Arten von Headern angegeben werden. Anfragen zur Quell- und Triggerregistrierung (einschließlich Weiterleitungen) werden bei einem Netzwerkfehler wiederholt. Die Anzahl der Wiederholungsversuche pro Anfrage ist auf eine feste Anzahl begrenzt, um erhebliche Auswirkungen auf das Gerät zu vermeiden.
Weiterleitungen werden fürregisterWebSource undenrollWebTrigger, die von Browsern verwendet werden, nicht akzeptiert. Weitere Informationen finden Sie im Leitfaden zur Implementierung von Websites für mehrere Websites und Apps.
Messdaten in Attributionsberichten ansehen
Mit der Attribution Reporting API können die folgenden Berichtstypen erstellt werden, die weiter unten auf dieser Seite genauer beschrieben werden:
- In Berichten auf Ereignisebene wird eine bestimmte Attributionsquelle (Klick oder Ansicht) mit begrenzten Bits von High-Fidelity-Trigger-Daten verknüpft.
- Zusammenfassungsfähige Berichte sind nicht unbedingt mit einer bestimmten Attributionsquelle verknüpft. Diese Berichte bieten umfassendere und zuverlässigere Triggerdaten als Berichte auf Ereignisebene. Sie sind jedoch nur in zusammengefasster Form verfügbar.
Diese beiden Berichtstypen ergänzen sich und können gleichzeitig verwendet werden.
Berichte auf Ereignisebene
Nachdem ein Trigger einer Attributionsquelle zugeordnet wurde, wird ein Bericht auf Ereignisebene generiert und auf dem Gerät gespeichert, bis er in einem der Zeitfenster für das Senden von Berichten an die Postback-URL der jeweiligen Anzeigentechnologie zurückgesendet werden kann. Weitere Informationen dazu finden Sie weiter unten auf dieser Seite.
Berichte auf Ereignisebene sind hilfreich, wenn nur sehr wenige Informationen zum Trigger erforderlich sind. Triggerdaten auf Ereignisebene sind auf 3 Bit an Triggerdaten für Klicks beschränkt. Einem Trigger kann also eine von acht Kategorien zugewiesen werden, und 1 Bit für Ansichten. Außerdem wird die Codierung von High-Fidelity-Daten auf Triggerseite, z. B. eines bestimmten Preises oder einer Auslösungszeit, in Berichten auf Ereignisebene nicht unterstützt. Da die Attribution auf Geräteebene erfolgt, werden in Berichten auf Ereignisebene keine geräteübergreifenden Analysen unterstützt.
Der Bericht auf Ereignisebene enthält u. a. folgende Daten:
- Ziel:Paketname der Werbetreibenden-App oder eTLD+1, bei dem der Trigger ausgelöst wurde
- ID der Attributionsquelle:Dies ist die ID der Attributionsquelle, die zum Registrieren einer Attributionsquelle verwendet wurde.
- Triggertyp: 1 oder 3 Bit Low-Fidelity-Triggerdaten, je nach Attributionsquelle
Datenschutzfreundliche Mechanismen, die auf alle Berichte angewendet werden
Die folgenden Limits werden angewendet, nachdem Prioritäten in Bezug auf Attributionsquellen und Trigger berücksichtigt wurden.
Begrenzung der Anzahl der Anzeigentechnologien
Die Anzahl der Anbieter von Anzeigentechnologien, die Berichte über die API registrieren oder empfangen können, ist begrenzt. Derzeit gilt Folgendes:
- 100 Anzeigentechnologien mit Attributionsquellen pro {Quell-App, Ziel-App, 30 Tage, Gerät}.
- 10 Anzeigentechnologien mit zugeordneten Triggern pro {Quell-App, Ziel-App, 30 Tage, Gerät}.
- 20 Anzeigentechnologien können eine einzelne Attributionsquelle oder einen einzelnen Trigger registrieren (über
Attribution-Reporting-Redirect
)
Beschränkungen für die Anzahl eindeutiger Ziele
Diese Limits erschweren es einer Reihe von Anzeigentechnologien, eine große Anzahl von Apps abzufragen, um das App-Nutzungsverhalten eines bestimmten Nutzers nachzuvollziehen.
- Die API unterstützt für alle registrierten Quellen und alle Anzeigentechnologien nicht mehr als 200 eindeutige Ziele pro Quell-App und Minute.
- Für alle registrierten Quellen unterstützt die API für eine einzelne Anzeigentechnologie nicht mehr als 50 eindeutige Ziele pro Quellanwendung und Minute. So wird verhindert, dass eine einzelne Anzeigentechnologie das gesamte Budget des zuvor genannten Preislimits aufbraucht.
Abgelaufene Quellen werden nicht auf die Ratenbegrenzungen angerechnet.
Ein Berichtsorigin pro Quell-App und Tag
Eine bestimmte AdTech-Plattform kann nur eine Berichtsquelle verwenden, um Quellen in einer Publisher-App für ein bestimmtes Gerät am selben Tag zu registrieren. Mit dieser Ratenbegrenzung wird verhindert, dass Anzeigentechnologie-Anbieter mehrere Berichtsquellen verwenden, um auf zusätzliches Datenschutzbudget zuzugreifen.
Stellen Sie sich folgendes Szenario vor: Eine einzelne Anzeigentechnologie möchte mehrere Berichtsquellen verwenden, um Quellen in einer Publisher-App für ein einzelnes Gerät zu registrieren.
- Mit der Berichtsquelle 1 von Anzeigentechnologie A wird eine Quelle in App B registriert
- 12 Stunden später versucht der Berichts-Ursprung 2 der Anzeigentechnologie A, eine Quelle in App B zu registrieren.
Die zweite Quelle, für die Berichtsquelle 2 der Anzeigentechnologie A, wird von der API abgelehnt. Die Berichtsquelle 2 von Ad Tech A kann erst am nächsten Tag eine Quelle auf demselben Gerät in App B registrieren.
Wartezeit und Ratenlimits
Um die Anzahl der Nutzeridentitäten, die zwischen einem {source, destination}-Paar preisgegeben werden, zu begrenzen, wird die Gesamtzahl der Informationen, die in einem bestimmten Zeitraum für einen Nutzer gesendet werden, von der API gedrosselt.
Derzeit wird vorgeschlagen, jede Anzeigentechnologie auf 100 zugeordnete Trigger pro {source app, destination app, 30 days, device} zu beschränken.
Anzahl der eindeutigen Ziele
Die API schränkt die Anzahl der Ziele ein, die eine Anzeigentechnologie messen kann. Je niedriger das Limit, desto schwieriger ist es für Anbieter von Anzeigentechnologien, mithilfe der API die Browseraktivitäten von Nutzern zu messen, die nicht mit ausgelieferten Anzeigen in Verbindung stehen.
Der aktuelle Vorschlag sieht vor, jede Anzeigentechnologie auf 100 verschiedene Ziele mit nicht abgelaufenen Quellen pro Quellanwendung zu beschränken.
Datenschutzfreundliche Mechanismen für Berichte auf Ereignisebene
Begrenzte Genauigkeit von Triggerdaten
Die API bietet 1 Bit für View-through-Trigger und 3 Bit für Klick-Trigger. Attributionsquellen unterstützen weiterhin die vollen 64 Bits an Metadaten.
Sie sollten prüfen, ob und wie Sie die in Triggern enthaltenen Informationen reduzieren können, damit sie mit der begrenzten Anzahl von Bits in Berichten auf Ereignisebene funktionieren.
Framework für Differential Privacy Noise
Ein Ziel dieser API ist es, die Messung auf Ereignisebene zu ermöglichen, um lokale Differential Privacy-Anforderungen zu erfüllen. Dazu werden mithilfe von k-zufälligen Antworten für jedes Quellereignis eine verrauschte Ausgabe generiert.
Rauschen wird darauf angewendet, ob ein Ereignis der Attributionsquelle wahrheitsgemäß gemeldet wird. Eine Attributionsquelle wird auf dem Gerät mit der Wahrscheinlichkeit $ 1-p $ registriert, dass die Attributionsquelle als normal registriert ist, und mit der Wahrscheinlichkeit $ p $, dass das Gerät nach dem Zufallsprinzip aus allen möglichen Ausgabestatus der API auswählt (einschließlich überhaupt nichts oder mehrere falsche Berichte).
Die k-zufällige Antwort ist ein Algorithmus, der epsilon-differential privat ist, wenn die folgende Gleichung erfüllt ist:
Bei niedrigen Werten von ε wird die tatsächliche Ausgabe durch den k-zufälligen Antwortmechanismus geschützt. Die genauen Rauschparameter sind noch in der Entwicklung und können sich je nach Feedback ändern. Es gibt derzeit einen Vorschlag:
- p=0,24 % für Navigationsquellen
- p=0,00025% für Ereignisquellen
Limits für verfügbare Trigger (Conversions)
Die Anzahl der Trigger pro Attributionsquelle ist begrenzt. Derzeit gilt Folgendes:
- 1–2 Trigger für Attributionsquellen für Anzeigenaufrufe (2 Trigger sind nur bei der Attribution nach der Installation verfügbar)
- 3 Trigger für Quellen der Klickattribution für Anzeigen
Bestimmte Zeitfenster für das Senden von Berichten (Standardverhalten)
Berichte auf Ereignisebene für Attributionsquellen für Anzeigenaufrufe werden eine Stunde nach Ablauf der Quelle gesendet. Dieses Ablaufdatum kann konfiguriert werden, kann jedoch nicht weniger als 1 Tag oder mehr als 30 Tage betragen. Wenn einer Attributionsquelle für Anzeigenaufrufe (über die Attribution nach der Installation) zwei Trigger zugeordnet sind, können Berichte auf Ereignisebene in den folgenden Berichtszeitraumintervallen gesendet werden.
Berichte auf Ereignisebene für Attributionsquellen für Anzeigenklicks können nicht konfiguriert werden. Sie werden vor oder nach Ablauf der Quelle zu einem bestimmten Zeitpunkt gesendet, der sich nach der Registrierung der Quelle richtet. Die Zeit zwischen Attributionsquelle und Ablauf wird in mehrere Berichtsfenster aufgeteilt. Jedes Berichtsfenster hat eine Frist (ab der Zeitangabe der Attributionsquelle). Am Ende jedes Berichtszeitraums erfasst das Gerät alle Trigger, die seit dem vorherigen Berichtszeitraum aufgetreten sind, und sendet einen geplanten Bericht. Die API unterstützt die folgenden Berichtsfenster:
- 2 Tage:Das Gerät erfasst alle Trigger, die höchstens 2 Tage nach der Registrierung der Attributionsquelle aufgetreten sind. Der Bericht wird 2 Tage und 1 Stunde nach der Registrierung der Attributionsquelle gesendet.
- 7 Tage:Das Gerät erfasst alle Trigger, die mehr als 2 Tage, aber nicht später als 7 Tage nach der Registrierung der Attributionsquelle aufgetreten sind. Der Bericht wird 7 Tage und 1 Stunde nach der Registrierung der Attributionsquelle gesendet.
- Eine benutzerdefinierte Zeitspanne, die durch das Attribut „expiry“ einer Attributionsquelle definiert wird. Der Bericht wird 1 Stunde nach der angegebenen Ablaufzeit gesendet. Dieser Wert kann nicht kleiner als 1 Tag oder mehr als 30 Tage sein.
Flexible Konfiguration auf Ereignisebene
Die Standardkonfiguration für Berichte auf Ereignisebene wird Werbetreibenden empfohlen, wenn sie mit Nutzwerttests beginnen. Sie ist jedoch möglicherweise nicht für alle Anwendungsfälle ideal. Die Attribution Reporting API unterstützt optionale und flexiblere Konfigurationen, damit Anzeigentechnologie-Anbieter mehr Kontrolle über die Struktur ihrer Berichte auf Ereignisebene haben und den Nutzen der Daten maximieren können.
Diese zusätzliche Flexibilität wird in zwei Phasen in die Attribution Reporting API eingeführt:
- Phase 1: Flexible Lite-Konfiguration auf Ereignisebene
- Diese Version bietet einen Teil des vollen Funktionsumfangs und kann unabhängig von Phase 2 verwendet werden.
- Phase 2: Vollversion der flexiblen Konfiguration auf Ereignisebene
Phase 1 (eingeschränkte flexible Ereignisebene) kann für Folgendes verwendet werden:
- Häufigkeit von Berichten durch Angabe der Anzahl der Berichtszeiträume variieren
- Anzahl der Attributionen pro Quellregistrierung variieren
- Reduzieren Sie den Gesamtrauschenpegel, indem Sie die oben genannten Parameter verringern.
- Berichtszeitraum konfigurieren, anstatt die Standardeinstellungen zu verwenden
In Phase 2 (vollständig flexible Ereignisebene) können alle Funktionen von Phase 1 verwendet werden und:
- Kardinalität der Triggerdaten in einem Bericht ändern
- Reduzieren Sie die Gesamtmenge an Rauschen, indem Sie die Kardinalität der Triggerdaten verringern.
Wenn eine Dimension der Standardkonfiguration reduziert wird, kann die Anzeigentechnologie eine andere Dimension erhöhen. Alternativ lässt sich der Gesamtanteil an Rauschen in einem Bericht auf Ereignisebene reduzieren, indem die oben genannten Parameter insgesamt verringert werden.
Zusätzlich zu den dynamisch festgelegten Rauschpegelwerten, die auf der ausgewählten Konfiguration der Anzeigentechnologie basieren, werden wir einige Parameterlimits festlegen, um hohe Rechenkosten und Konfigurationen mit zu vielen Ausgabezuständen zu vermeiden, bei denen der Rauschpegel erheblich ansteigt. Hier ist ein Beispiel für eine Reihe von Einschränkungen. Wir freuen uns über Feedback zum [Designvorschlag][50]:
- Maximal 20 Berichte insgesamt, global und pro „trigger_data“
- Maximal 5 mögliche Berichtszeiträume pro „trigger_data“
- Maximal 32 Triggerdaten mit Kardinalität (nicht zutreffend für Phase 1: Lite-Flexible Event Level)
AdTech-Experten beginnen mit der Nutzung dieser Funktion. Beachten Sie, dass die Verwendung von Extremwerten zu starkem Rauschen führen kann oder zu einem Fehler bei der Registrierung führen kann, wenn die Datenschutzstufen nicht eingehalten werden.
Aggregierbare Berichte
Bevor Sie aggregierbare Berichte verwenden können, müssen Sie Ihr Cloud-Konto einrichten und zusammenfassende Berichte erhalten.
Aggregierbare Berichte liefern schneller und genauere Triggerdaten vom Gerät als Berichte auf Ereignisebene. Diese genaueren Daten können nur in Aggregierung erlernt werden und sind keinem bestimmten Trigger oder Nutzer zugeordnet. Aggregationsschlüssel können bis zu 128 Bit lang sein. So können Berichte mit zusammengefassten Daten folgende Anwendungsfälle unterstützen:
- Berichte für Triggerwerte wie „Umsatz“
- Mehr Triggertypen verarbeiten
Darüber hinaus verwenden aggregierte Berichte dieselbe quellenpriorisierte Attributionslogik wie Berichte auf Ereignisebene, unterstützen aber mehr Conversions, die einem Klick oder einer Ansicht zugeordnet werden.
Wie im Diagramm dargestellt, wie durch die Attribution Reporting API aggregierte Berichte vorbereitet und gesendet werden:
- Das Gerät sendet verschlüsselte, aggregierte Berichte an den Anzeigentechnologie-Anbieter. In einer Produktionsumgebung können diese Berichte nicht direkt verwendet werden.
- Die Anzeigentechnologie sendet eine Reihe von aggregierbaren Berichten zur Aggregation an den Aggregationsdienst.
- Der Aggregationsdienst liest einen Batch aggregierter Berichte, entschlüsselt und aggregiert sie.
- Die endgültigen zusammengefassten Daten werden in einem Zusammenfassungsbericht an die Anzeigentechnologie gesendet.
Aggregierte Berichte enthalten die folgenden Daten in Bezug auf Attributionsquellen:
- Ziel: Der Paketname der App oder die Web-URL mit eTLD+1, unter der der Trigger ausgelöst wurde.
- Datum:Das Datum, an dem das durch die Attributionsquelle dargestellte Ereignis aufgetreten ist.
- Nutzlast: Triggerwerte, die als verschlüsselte Schlüssel/Wert-Paare erfasst werden und im vertrauenswürdigen Aggregationsdienst zum Berechnen von Aggregationen verwendet werden.
Aggregationsdienste
Die folgenden Dienste bieten Aggregationsfunktionen und schützen vor unzulässigem Zugriff auf Aggregationsdaten.
Diese Dienste werden von verschiedenen Parteien verwaltet, die weiter unten auf dieser Seite genauer beschrieben werden:
- Der Aggregationsdienst ist der einzige, den Anbieter von Anzeigentechnologien bereitstellen müssen.
- Die Dienste zur Schlüsselverwaltung und zur aggregierbaren Berichtserfassung werden von vertrauenswürdigen Dritten namens Koordinatoren ausgeführt. Diese Koordinatoren bestätigen, dass der Code, mit dem der Aggregationsdienst ausgeführt wird, der öffentlich verfügbare Code von Google ist und dass für alle Nutzer des Aggregationsdienstes derselbe Schlüssel und dieselben aggregierbaren Berichtsbuchhaltungsdienste verwendet werden.
Aggregationsdienst
Anbieter von AdTech-Plattformen müssen vorab einen Aggregationsdienst bereitstellen, der auf von Google bereitgestellten Binärdateien basiert.
Dieser Aggregationsdienst wird in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt, die in der Cloud gehostet wird. Ein TEE bietet die folgenden Sicherheitsvorteile:
- So wird sichergestellt, dass der im TEE ausgeführte Code die von Google angebotene Binärdatei ist. Solange diese Bedingung nicht erfüllt ist, kann der Aggregationsdienst nicht auf die für die Ausführung erforderlichen Entschlüsselungsschlüssel zugreifen.
- Sie bietet Sicherheit für den laufenden Prozess und isoliert ihn von externer Überwachung oder Manipulation.
Diese Sicherheitsvorteile machen es einem Aggregationsdienst sicherer, sensible Vorgänge wie den Zugriff auf verschlüsselte Daten auszuführen.
Weitere Informationen zu Design, Workflow und Sicherheitsaspekten des Aggregationsdienstes finden Sie im Dokument zum Aggregationsdienst auf GitHub.
Key Management Service
Dieser Dienst prüft, ob ein Aggregationsdienst eine genehmigte Version der Binärdatei ausführt, und stellt dem Aggregationsdienst in der Anzeigentechnologie dann die richtigen Entschlüsselungsschlüssel für die Triggerdaten zur Verfügung.
Berichtserfassung, die aggregiert werden kann
Dieser Dienst erfasst, wie oft der Aggregationsdienst einer Anzeigentechnologie auf einen bestimmten Trigger zugreift, der mehrere Aggregationsschlüssel enthalten kann. Der Zugriff wird auf die entsprechende Anzahl von Entschlüsselungen beschränkt. Weitere Informationen finden Sie im Designvorschlag für den Aggregationsdienst für die Attribution Reporting API.
Aggregatable Reports API
Die API zum Erstellen von Beiträgen zu aggregierbaren Berichten verwendet dieselbe Basis-API wie beim Registrieren einer Attributionsquelle für Berichte auf Ereignisebene. In den folgenden Abschnitten werden die Erweiterungen der API beschrieben.
Aggregierbare Quelldaten registrieren
Wenn die API eine Anfrage an den URI der Attributionsquelle sendet, kann die Anzeigentechnologie eine Liste von Aggregationsschlüsseln mit dem Namen histogram_contributions
registrieren, indem sie im HTTP-Header Attribution-Reporting-Register-Source
mit einem neuen Feld namens aggregation_keys
antwortet, wobei key_name
als Schlüssel und key_piece
als Wert verwendet wird:
- (Schlüssel) Schlüsselname:Ein String für den Namen des Schlüssels. Wird als Join-Schlüssel verwendet, um ihn mit schlüsselseitigen Schlüsseln zu kombinieren, um den endgültigen Schlüssel zu bilden.
- (Wert) Schlüsselelement: Ein Bitstringwert für den Schlüssel.
Der endgültige Histogramm-Bucket-Schlüssel wird zum Zeitpunkt des Auslösers vollständig definiert, indem auf diese Teile und die triggerseitigen Teile ein binärer OR-Vorgang angewendet wird.
Endgültige Schlüssel sind auf maximal 128 Bit beschränkt. Schlüssel, die länger sind, werden abgeschnitten. Hexadezimal-Strings in JSON sollten also auf maximal 32 Ziffern beschränkt sein.
Weitere Informationen zur Strukturierung und Konfiguration von Aggregationsschlüsseln finden Sie hier.
Im folgenden Beispiel erfasst ein Anzeigentechnologie-Anbieter über die API Folgendes:
- Conversion-Anzahl auf Kampagnenebene zusammenfassen
- Kaufwerte auf geografischer Ebene zusammenfassen
// This is where the Attribution-Reporting-Register-Source object appears when // an ad tech registers an attribution source. // Attribution source metadata specifying histogram contributions in aggregate report. Attribution-Reporting-Register-Source: … aggregation_keys: { // Generates a "0x159" key piece named (low order bits of the key) for the key // named "campaignCounts". // User saw an ad from campaign 345 (out of 511). "campaignCounts": "0x159", // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue" // Source-side geo region = 5 (US), out of a possible ~100 regions. "geoValue": "0x5" }
Aggregierbaren Trigger registrieren
Die Triggerregistrierung enthält zwei zusätzliche Felder.
Das erste Feld wird verwendet, um eine Liste aggregierter Schlüssel auf Triggerseite zu registrieren. Die Anzeigentechnologie sollte mit dem Feld aggregatable_trigger_data
im HTTP-Header Attribution-Reporting-Register-Trigger
antworten und für jeden zusammengefassten Schlüssel in der Liste die folgenden Felder enthalten:
- Schlüsselelement: Ein Bitstringwert für den Schlüssel.
- Quellschlüssel:Eine Liste von Strings mit den Namen der Seitenschlüssel der Attribution, mit denen der Triggerschlüssel kombiniert werden soll, um die endgültigen Schlüssel zu bilden.
Im zweiten Feld wird eine Liste von Werten registriert, die zu jedem Schlüssel beitragen sollen. Die Anzeigentechnologie sollte mit dem Feld aggregatable_values
im HTTP-Header Attribution-Reporting-Register-Trigger
antworten. Im zweiten Feld wird eine Liste von Werten registriert, die zu jedem Schlüssel beitragen sollen. Dies können Ganzzahlen im Bereich $ [1, 2^{16}] $ sein.
Jeder Trigger kann mehrere Beiträge zu den aggregierten Berichten leisten. Die Gesamtzahl der Beiträge zu einem bestimmten Quellereignis ist durch einen $ L1 $-Parameter gebunden. Dieser entspricht der maximalen Summe der Beiträge (Werte) aller aggregierten Schlüssel für eine bestimmte Quelle. $ L1 $ bezieht sich auf die L1-Empfindlichkeit oder Norm der Histogramm-Beiträge pro Quellereignis. Wenn Sie diese Limits überschreiten, werden zukünftige Beiträge automatisch gelöscht. Der ursprüngliche Vorschlag besteht darin, $ L1 $ auf $ 2^{16} $ (65.536) festzulegen.
Das Rauschen im Aggregationsdienst wird proportional zu diesem Parameter skaliert. Daher wird empfohlen, die für einen bestimmten zusammengefassten Schlüssel gemeldeten Werte entsprechend dem zugewiesenen Anteil des L1-Budgets zu skalieren. So wird sichergestellt, dass die zusammengefassten Berichte bei der Anwendung von Rauschen möglichst genau bleiben. Dieser Mechanismus ist äußerst flexibel und kann viele Aggregationsstrategien unterstützen.
Im folgenden Beispiel wird das Datenschutzbudget gleichmäßig zwischen campaignCounts
und geoValue
aufgeteilt. Dabei wird der Beitrag von $ L1 $ auf beide aufgeteilt:
// This is where the Attribution-Reporting-Register-Trigger object appears // when an ad tech registers a conversion trigger. // Specify a list of dictionaries that generates aggregation keys. Attribution-Reporting-Register-Trigger:{ … "aggregatable_trigger_data": [ // Each dictionary independently adds pieces to multiple source keys. { // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9. // A 9-bit offset is needed because there are 511 possible campaigns, which // will take up 9 bits in the resulting key. "key_piece": "0x400",// Conversion type purchase = 2 // Apply this key piece to: "source_keys": ["campaignCounts"] }, { // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7. // A 7-bit offset is needed because there are ~100 regions for the geo key, // which will take up 7 bits of space in the resulting key. "key_piece": "0xA80", // Apply this key piece to: "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"] } ] // Specify an amount of an abstract value which can be integers in [1, 2^16] to // contribute to each key that is attached to aggregation keys in the order that // they're generated. aggregatable_values: { // Privacy budget for each key is L1 / 2 = 2^15 (32768). // Conversion count was 1. // Scale the count to use the full budget allocated: 1 * 32768 = 32768. "campaignCounts": 32768, // Purchase price was $52. // Purchase values for the app range from $1 to $1,024 (integers only). // Scaling factor applied is 32768 / 1024 = 32. // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664). "geoValue": 1664 } }
Das vorherige Beispiel generiert die folgenden Histogrammbeiträge:
[
// campaignCounts:
{
"key": "0x559", // = 0x159 | 0x400
"value": 32768
},
// geoValue:
{
"key": "0xA85", // = 0x5 | 0xA80
"value": 1664
}
]
Die Skalierungsfaktoren können invertiert werden, um die richtigen Werte bzw. das angewendete Modulo-Rauschen zu erhalten:
L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024
Differential Privacy
Ein Ziel dieser API ist es, ein Framework zu schaffen, das differenziell private aggregierte Messungen unterstützt. Dies kann erreicht werden, indem das Rauschen proportional zum Budget von $ L1 $ hinzugefügt wird, z. B. durch Auswahl des Rauschens mit der folgenden Verteilung:
Integration der Protected Audience API und der Attribution Reporting API
Durch die API-übergreifende Integration der Protected Audience API und der Attribution Reporting API können Anbieter von Anzeigentechnologien ihre Attributionsleistung für verschiedene Remarketing-Taktiken bewerten, um herauszufinden, welche Zielgruppen den höchsten ROI erzielen.
Durch diese API-übergreifende Integration haben Anbieter von Anzeigentechnologien folgende Möglichkeiten:
- Erstellen Sie eine Schlüssel/Wert-Zuordnung von URIs, die sowohl für 1) Interaktionsberichte und 2) Quellenregistrierung verwendet werden soll.
- Fügen Sie
CustomAudience
in die schlüsselseitige Zuordnung auf Quellseite für zusammengefasste Berichte (mit der Attribution Reporting API) ein.
Wenn ein Nutzer eine Anzeige sieht oder darauf klickt:
- Die URL, über die diese Interaktionen mithilfe der Protected Audience API erfasst werden, wird auch verwendet, um einen Aufruf oder Klick als berechtigte Quelle mit der Attribution Reporting API zu registrieren.
- Die Anzeigentechnologie kann CustomAudience oder andere relevante Kontextinformationen zur Anzeige (z. B. Anzeigen-Placement oder Wiedergabedauer) über diese URL übergeben, damit diese Metadaten in zusammenfassenden Berichten weitergegeben werden können, wenn sie die zusammengefasste Kampagnenleistung überprüft.
Weitere Informationen dazu, wie diese Funktion in Protected Audience aktiviert wird, finden Sie im entsprechenden Abschnitt der Erklärung zur Protected Audience API.
Beispiele für Registrierungspriorität, Attribution und Berichte
In diesem Beispiel wird eine Reihe von Nutzerinteraktionen gezeigt und es wird gezeigt, wie sich die durch AdTech definierte Attributionsquelle und die Triggerprioritäten auf zugeordnete Berichte auswirken können. In diesem Beispiel gehen wir von Folgendem aus:
- Alle Attributionsquellen und -trigger werden von derselben Anzeigentechnologie für denselben Werbetreibenden registriert.
- Alle Attributionsquellen und -trigger werden im ersten Berichtszeitraum (innerhalb von zwei Tagen nach der ersten Auslieferung der Anzeigen in einer Publisher-App) ausgeführt.
Stellen Sie sich den Fall vor, bei dem Nutzende Folgendes tun:
- Der Nutzer sieht eine Anzeige. Die Anzeigentechnologie registriert eine Attributionsquelle mit der Priorität
0
(Ansicht 1). - Der Nutzer sieht eine Anzeige mit der Priorität
0
(Aufruf 2). - Der Nutzer klickt auf eine Anzeige mit der Priorität
1
(Klick 1). - Der Nutzer tätigt eine Conversion (erreicht die Landingpage) in der App eines Werbetreibenden. Die Anzeigentechnologie registriert einen Trigger bei der API mit der Priorität
0
(Conversion 1).- Wenn Trigger registriert werden, führt die API zuerst eine Attribution durch, bevor Berichte generiert werden.
- Es sind drei Attributionsquellen verfügbar: Aufruf 1, Aufruf 2 und Klick 1. Die API ordnet diesen Trigger dem Klick 1 zu, da er die höchste Priorität hat und der jüngste ist.
- Die Daten zu Datenaufruf 1 und Datenaufruf 2 werden verworfen und können nicht mehr für zukünftige Attributionen verwendet werden.
- Der Nutzer legt in der App des Werbetreibenden einen Artikel in den Einkaufswagen, der mit der Priorität
1
(Conversion 2) registriert wurde.- Klick 1 ist die einzige zulässige Attributionsquelle. Die API-Attribute liefern diesen Trigger, um auf „#1“ zu klicken.
- Der Nutzer legt in der App des Werbetreibenden einen Artikel in den Einkaufswagen, der mit der Priorität
1
registriert ist (Conversion 3).- Klick 1 ist die einzige zulässige Attributionsquelle. Die API-Attribute liefern diesen Trigger, um auf „#1“ zu klicken.
- Der Nutzer legt in der App des Werbetreibenden einen Artikel in den Einkaufswagen, der mit der Priorität
1
(Conversion 4) registriert ist.- Klick 1 ist die einzige zulässige Attributionsquelle. Die API-Attribute dieses Triggers fordern zum Klicken auf 1 auf.
- Der Nutzer tätigt einen Kauf in der Werbetreibenden-App, die mit der Priorität
2
(Conversion 5) registriert ist.- Klick 1 ist die einzige zulässige Attributionsquelle. Die API-Attribute liefern diesen Trigger, um auf „#1“ zu klicken.
Berichte auf Ereignisebene haben folgende Merkmale:
- Standardmäßig werden die ersten drei Trigger, die einem Klick zugeordnet sind, und der erste Trigger, der einer Ansicht zugeordnet ist, nach den entsprechenden Berichtsfenstern gesendet.
- Wenn im Berichtszeitraum Trigger mit höherer Priorität registriert sind, haben diese Vorrang und ersetzen den jeweils letzten Trigger.
- Im vorherigen Beispiel erhält die Anzeigentechnologie nach dem zweitägigen Berichtszeitraum drei Ereignisberichte für Conversion 2, Conversion 3 und Conversion 5.
- Alle fünf Trigger werden Klick 1 zugeordnet. Standardmäßig sendet die API Berichte für die ersten drei Trigger: Conversion 1, Conversion 2 und Conversion 3.
- Die Priorität von Conversion 4 (
1
) ist jedoch höher als die Priorität von Conversion 1 (0
). Der Ereignisbericht von Conversion 4 ersetzt den zu sendenden Ereignisbericht von Conversion 1. - Außerdem ist die Priorität von Conversion 5 (
2
) höher als bei jedem anderen Trigger. Der Bericht „Ereignis“ von Conversion 5 ersetzt den zu sendenden Bericht von Conversion 4.
Für Berichte, die zusammengefasst werden können, gelten die folgenden Eigenschaften:
Verschlüsselte aggregierbare Berichte werden an die Anzeigentechnologie gesendet, sobald sie verarbeitet wurden, also einige Stunden nach der Registrierung der Trigger.
Als Anzeigentechnologie-Anbieter erstellen Sie Batches anhand der Informationen, die in Ihren aggregierten Berichten unverschlüsselt sind. Diese Informationen sind im Feld
shared_info
Ihres aggregierten Berichts enthalten. Dazu gehören der Zeitstempel und der Ursprung der Berichterstellung. Es ist nicht möglich, Batches basierend auf verschlüsselten Informationen in den zusammengefassten Schlüssel/Wert-Paaren zu erstellen. Sie können beispielsweise Berichte täglich oder wöchentlich im Batch erstellen. Idealerweise sollten Batches jeweils mindestens 100 Berichte enthalten.Die Entscheidung, wann und wie die aggregierbaren Berichte in Batches zusammengefasst und an den Aggregationsdienst gesendet werden, liegt beim Anbieter der Anzeigentechnologie.
Im Vergleich zu Berichten auf Ereignisebene können verschlüsselte aggregierte Berichte einer Quelle mehr Trigger zuordnen.
Im vorherigen Beispiel werden fünf aggregierte Berichte gesendet, einer für jeden registrierten Trigger.
Berichte zur Übergangsphase
Die Attribution Reporting API ist eine neue und relativ komplexe Möglichkeit, die Attributionsmessung ohne App-übergreifende Kennungen durchzuführen. Aus diesem Grund unterstützen wir einen Übergangsmechanismus, um mehr über Attributionsberichte zu erfahren, wenn die Werbe-ID verfügbar ist (der Nutzer hat die Personalisierung nicht über die Werbe-ID deaktiviert und der Publisher oder die App des Werbetreibenden hat AdID-Berechtigungen erklärt). So ist die API während der Einführung vollständig verständlich. Außerdem werden Fehler behoben und die Leistung lässt sich leichter mit Alternativen auf Basis der Werbe-ID vergleichen. Es gibt zwei Arten von Debugging-Berichten: Attribution-Erfolgsberichten und ausführliche Berichte.
Weitere Informationen zur Fehlerbehebung in Berichten mit App-zu-Web- und Web-zu-App-Messungen finden Sie im Leitfaden zu Transitional-Debugging-Berichten.
Berichte zur Fehlerbehebung bei erfolgreicher Attribution
Für Quell- und Triggerregistrierungen kann beide ein neues 64-Bit-Feld debug_key
(formatiert als String) verwendet werden, das von der Anzeigentechnologie ausgefüllt wird. source_debug_key
und trigger_debug_key
werden sowohl in Berichten auf Ereignisebene als auch in aggregierten Berichten unverändert übergeben.
Wenn ein Bericht sowohl mit Quell- als auch mit Trigger-Fehlerbehebungsschlüsseln erstellt wird, wird ein duplizierter Debug-Bericht mit begrenzter Verzögerung an einen .well-known/attribution-reporting/debug/report-event-attribution
-Endpunkt gesendet. Die Fehlerbehebungsberichte sind mit normalen Berichten identisch und enthalten die beiden wichtigsten Felder für die Fehlerbehebung.
Wenn diese Schlüssel in beiden enthalten sind, können normale Berichte mit dem separaten Stream von Fehlerbehebungsberichten verknüpft werden.
- Für Berichte auf Ereignisebene:
- Duplikate von Debugberichten werden mit nur kurzer Verzögerung gesendet und daher nicht durch Einschränkungen der verfügbaren Trigger unterdrückt. So können Anbieter von Anzeigentechnologien die Auswirkungen dieser Einschränkungen auf Berichte auf Ereignisebene nachvollziehen.
- Berichte auf Ereignisebene, die mit falsch ausgelösten Ereignissen verknüpft sind, enthalten keine
trigger_debug_key
. So kann die Anzeigentechnologie besser verstehen, wie Rauschen in der API angewendet wird.
- Für aggregierbare Berichte:
- Das neue Feld
debug_cleartext_payload
, das die entschlüsselte Nutzlast enthält, wird nur unterstützt, wenn sowohlsource_debug_key
als auchtrigger_debug_key
festgelegt sind.
- Das neue Feld
Ausführliche Debugging-Berichte
Mit ausführlichen Debugging-Berichten können Entwickler bestimmte Fehler in der Attributionsquelle oder bei Triggerregistrierungen beobachten. Diese Berichte zur Fehlerbehebung werden nach der Registrierung von Attributionsquellen oder Triggern mit einer kurzen Verzögerung an einen gesendet.well-known/attribution-reporting/debug/verbose
-Endpunkt.
Jeder ausführliche Bericht enthält die folgenden Felder:
- Typ: Gibt an, was zum Generieren des Berichts geführt hat. Vollständige Liste der ausführlichen Berichtstypen
- Im Allgemeinen werden ausführliche quellenbasierte Berichte generiert, die ausführlichere Berichte auslösen.
- Für ausführliche Berichte zu Quellen muss die Werbe-ID für die Publisher-App verfügbar sein. Für ausführliche Berichte zu Auslösern muss die Werbe-ID für die App des Werbetreibenden verfügbar sein.
- Ausführliche Triggerberichte (mit Ausnahme von
trigger-no-matching-source
) können optional dassource_debug_key
enthalten. Dieser Name kann nur angegeben werden, wenn die Werbe-ID auch für die Publisher-App verfügbar ist.
- Text: Der Textkörper des Berichts, abhängig vom Typ.
Anzeigentechnologie-Anbieter müssen den Erhalt ausführlicher Debugging-Berichte aktivieren. Hierzu wird ein neues debug_reporting
-Wörterbuchfeld in den Headern Attribution-Reporting-Register_Source
und Attribution-Reporting-Register-Trigger
verwendet.
- Für ausführliche Berichte zu Quellen ist nur eine Aktivierung in der Kopfzeile der Quellenregistrierung erforderlich.
- Für Berichte zum Debuggen von Triggern muss nur die Kopfzeile der Triggerregistrierung aktiviert werden.
Fehlerbehebungsberichte verwenden
Wenn gemäß Ihrem vorhandenen Messsystem eine Konvertierung stattgefunden hat und für diese Konvertierung ein Debug-Bericht empfangen wurde, bedeutet dies, dass der Trigger erfolgreich registriert wurde.
Prüfen Sie für jeden Attributionsbericht für die Fehlerbehebung, ob Sie einen regulären Attributionsbericht erhalten, der mit den beiden Fehlerbehebungsschlüsseln übereinstimmt.
Wenn keine Übereinstimmung gefunden wird, kann das verschiedene Gründe haben.
Funktioniert wie vorgesehen:
- Datenschutzfreundliche API-Verhaltensweisen:
- Ein Nutzer erreicht die Ratenbegrenzung für Berichte. Dadurch werden keine weiteren Berichte im entsprechenden Zeitraum gesendet oder eine Quelle wird aufgrund des ausstehenden Ziellimits entfernt.
- Bei Berichten auf Ereignisebene: Der Bericht unterliegt einer zufälligen Antwort (Verrausch) und wird unterdrückt. Eventuell erhalten Sie auch einen zufälligen Bericht.
- Bei Berichten auf Ereignisebene: Das Limit von drei (für Klicks) oder einem (für Datenansichten) Bericht wurde erreicht und für nachfolgende Berichte wurde keine explizite Priorität festgelegt oder eine Priorität, die niedriger ist als bei vorhandenen Berichten.
- Die Beitragslimits für aggregierbare Berichte wurden überschritten.
- Von AdTech definierte Geschäftslogik:
- Trigger werden über Filter oder Prioritätsregeln herausgefiltert.
- Zeitverzögerungen oder Interaktionen mit der Netzwerkverfügbarkeit (z. B. wenn der Nutzer sein Gerät für einen längeren Zeitraum ausschaltet)
Unbeabsichtigte Ursachen:
- Probleme bei der Implementierung:
- Der Quellheader ist falsch konfiguriert.
- Der Trigger-Header ist falsch konfiguriert.
- Sonstige Konfigurationsprobleme.
- Geräte- oder Netzwerkprobleme:
- Ausfälle aufgrund von Netzwerkbedingungen.
- Die Antwort auf die Registrierung der Quelle oder des Triggers erreicht den Client nicht.
- API-Fehler.
Zukünftige Überlegungen und offene Fragen
Die Attribution Reporting API befindet sich noch in der Entwicklungsphase. Außerdem erforschen wir zukünftige mögliche Funktionen wie Attributionsmodelle, die nicht auf dem letzten Klick basieren, und Anwendungsfälle für die geräteübergreifende Messung.
Außerdem möchten wir von der Community Feedback zu einigen Themen einholen:
- Gibt es Anwendungsfälle, in denen Sie möchten, dass die API Berichte für die bestätigte Installation sendet? Diese Berichte werden auf die jeweiligen Ratenbegrenzungen für Anzeigentechnologie-Plattformen angerechnet.
- Gibt es Schwierigkeiten bei der Übergabe der
InputEvent
von der App an die Anzeigentechnologie zur Quellenregistrierung? - Haben Sie spezielle Anwendungsfälle für die Attribution bei vorinstallierten oder neu installierten Apps?