Attribution Reporting API: Integrationsanleitung

Wähle beim Lesen der Dokumentation zur Privacy Sandbox für Android über die Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der du arbeitest. Die Anleitung kann davon abweichen.

Die Attribution Reporting API unterstützt wichtige Anwendungsfälle für die Attribution und Conversion-Messung in Apps und im Web, ohne dabei auf anbieterübergreifende Nutzer-IDs angewiesen zu sein. Im Vergleich zu gängigen Designs sollten die Implementierung der Attribution Reporting API einige wichtige Aspekte berücksichtigen:

  • Berichte auf Ereignisebene enthalten Low-Fidelity-Conversion-Daten. Eine kleine Anzahl von Conversion-Werten funktioniert gut.
  • Aggregierbare Berichte enthalten aussagekräftigere Conversion-Daten. Ihre Lösungen sollten Aggregationsschlüssel basierend auf Ihren Geschäftsanforderungen und der 128-Bit-Grenze entwerfen.
  • Für die Datenmodelle und die Verarbeitung Ihrer Lösung sollten Ratenbegrenzungen für verfügbare Trigger, Zeitverzögerungen beim Senden von Triggerereignissen und von der API angewendetes Rauschen berücksichtigt werden.

Dieser Leitfaden soll dich bei der Planung der Integration unterstützen. Er umfasst eine umfassende Übersicht über Funktionen, die im aktuellen Stadium der Privacy Sandbox für die Android-Entwicklervorschau noch nicht implementiert wurden. In diesen Fällen wird eine Zeitplan-Anleitung bereitgestellt.

Auf dieser Seite verwenden wir Quelle, um entweder einen Klick oder einen Aufruf darzustellen, und Trigger, um eine Conversion darzustellen.

Das folgende Diagramm zeigt die verschiedenen Workflowoptionen für die Attributionsintegration. Abschnitte in derselben Spalte (grün eingekreist) können parallel bearbeitet werden. So kann beispielsweise die Interaktion mit einem Partner gleichzeitig mit der Attribution auf App-zu-App-Ereignisebene erfolgen.

Workflowdiagramm für die Attributionsintegration

Abbildung 1: Workflow für die Attributionsintegration

Voraussetzungen und Einrichtung

In diesem Abschnitt erfahren Sie mehr über die Attribution Reporting API. Mit diesen Schritten erhalten Sie aussagekräftige Ergebnisse, wenn Sie die API in der AdTech-Umgebung verwenden.

Mit der API vertraut machen

  1. Lesen Sie den Designvorschlag, um sich mit der Attribution Reporting API und ihren Funktionen vertraut zu machen.
  2. Im Entwicklerleitfaden erfahren Sie, wie Sie den Code und die API-Aufrufe einbinden, die Sie für Ihre Anwendungsfälle benötigen.
  3. Senden Sie Ihr Feedback zur Dokumentation, insbesondere zu den offenen Fragen.
  4. Registrieren Sie sich, um Updates zur Attribution Reporting API zu erhalten. So bleiben Sie über neue Funktionen auf dem Laufenden, die in zukünftigen Versionen eingeführt werden.

Beispiel-App einrichten und testen

  1. Sobald du bereit bist, mit der Integration zu beginnen, richte dich mit der neuesten Entwicklervorschau in Android Studio ein.
  2. Richten Sie simulierte Serverendpunkte für Ereignisregistrierungen und Übermittlungen von Berichten ein. Wir stellen Ihnen Beispiele zur Verfügung, die Sie in Verbindung mit den online verfügbaren Tools verwenden können.
  3. Laden Sie den Code aus unserer Beispiel-App herunter und führen Sie ihn aus, um sich mit dem Registrieren von Quellen und Triggern vertraut zu machen.
    1. Legen Sie das Zeitfenster für das Senden von Berichten fest. Die API unterstützt Zeiträume von 2 Tagen, 7 Tagen oder einen benutzerdefinierten Zeitraum zwischen 2 und 30 Tagen.
    2. Nachdem Sie Quellen und Trigger durch Ausführen und Verwenden der Beispielanwendung registriert haben und der festgelegte Zeitraum abgelaufen ist, prüfen Sie, ob Sie einen Bericht auf Ereignisebene und einen verschlüsselten aggregierten Bericht erhalten haben. Wenn Sie Fehler in Berichten beheben müssen, können Sie diese schneller generieren, indem Sie die Ausführung von Berichterstellungsjobs erzwingen.
    3. Sehen Sie sich die Ergebnisse für die App-zu-App-Attribution an. Prüfen Sie, ob die Daten in diesen Ergebnissen sowohl für die letzte Interaktion als auch für die Fälle nach der Installation den Erwartungen entsprechen.

  4. Wenn du ein Gefühl dafür hast, wie die Client-API und der Server zusammenarbeiten, kannst du die Beispiel-App als Beispiel für deine eigene Integration verwenden. Richten Sie Ihren eigenen Produktionsserver ein und fügen Sie Ihren Anwendungen Aufrufe zur Ereignisregistrierung hinzu.

Vor der Integration

Registrieren Sie Ihre Organisation für die Privacy Sandbox für Android. Diese Registrierung dient dazu, unnötige Duplikate von AdTech-Plattformen zu vermeiden, die Zugriff auf mehr Informationen ermöglichen würden, als zu den Aktivitäten des Nutzers erforderlich sind.

Partnerinteraktion

AdTech-Partner (MMP/SSP/DSP) entwickeln häufig integrierte Attributionslösungen. Die Schritte in diesem Abschnitt helfen Ihnen, sich auf eine erfolgreiche Zusammenarbeit mit Ihren AdTech-Partnern vorzubereiten.

  1. Vereinbaren Sie ein Gespräch mit Ihren wichtigsten Analysepartnern, um das Testen und die Einführung der Attribution Reporting API zu besprechen. Zu den Analysepartnern gehören AdTech-Netzwerke, SSPs, DSPs, Werbetreibende oder andere Partner, mit denen Sie derzeit zusammenarbeiten oder mit denen Sie zusammenarbeiten möchten.
  2. Arbeiten Sie mit Ihren Analysepartnern zusammen, um Zeitpläne für die Integration zu definieren – von den ersten Tests bis zur Einführung.
  3. Klären Sie mit Ihren Analysepartnern, welche Bereiche Sie bei der Attributionsplanung behandeln werden.
  4. Kommunikationskanäle zwischen Messpartnern einrichten, um Zeitpläne und End-to-End-Tests zu synchronisieren
  5. Entwerfen Sie einen übergeordneten Datenfluss für Messungen von Partnern. Hier einige wichtige Überlegungen:
    • Wie können Partner für Messungen Attributionsquellen bei der Attribution Reporting API registrieren?
    • Wie registrieren Anzeigentechnologie-Netzwerke Trigger mit der Attribution Reporting API?
    • Wie validiert die jeweilige Anzeigentechnologie API-Anfragen, gibt Antworten auf die vollständige Quelle zurück und löst Registrierungen aus?
    • Gibt es Berichte, die mit Partnern außerhalb der Attribution Reporting API geteilt werden müssen?
    • Sind weitere Integrationspunkte oder eine Abstimmung zwischen den Partnern erforderlich? Müssen Sie und Ihre Partner beispielsweise an Deduplizierung von Conversions arbeiten oder sich an Aggregationsschlüsseln einigen?
  6. Wenn App-zu-Web-Attribution möglich ist, sollten Sie ein Gespräch mit Analysepartnern im Web vereinbaren, um das Design, die Tests und die Einführung der Attribution Reporting API zu besprechen. Beziehen Sie sich bei Gesprächen mit Webpartnern mit den Fragen aus dem vorherigen Schritt.

Prototypen für Attribution von App-zu-App-Ereignissen erstellen

In diesem Abschnitt erfahren Sie, wie Sie eine einfache App-zu-App-Attribution mit Berichten auf Ereignisebene in Ihrer App oder Ihrem SDK einrichten. Sie müssen diesen Abschnitt abschließen, bevor Sie mit der Prototyperstellung für die Aggregationsserverzuordnung beginnen können.

  1. Richten Sie einen Erfassungsserver für Ereigniseinträge ein. Dazu können Sie die bereitgestellte Spezifikation verwenden, um einen Testserver zu generieren, oder Ihren eigenen Server mit dem Beispielservercode einrichten.
  2. Fügen Sie Ihrem SDK oder Ihrer App Aufrufe zur Registrierung von Quellereignissen hinzu, wenn Anzeigen ausgeliefert werden.
    • Wichtige Überlegungen:
      • Achten Sie darauf, dass Quellereignis-IDs verfügbar sind und korrekt an die Aufrufe der Quellenregistrierungs-API übergeben werden.
      • Achten Sie darauf, dass Sie auch ein „InputEvent“ übergeben können, um Klickquellen zu registrieren.
      • Legen Sie die Konfiguration der Quellenpriorität für verschiedene Ereignistypen fest. Weisen Sie beispielsweise Ereignissen, die als umsatzstark eingestuft werden, wie Klicks gegenüber Aufrufen eine hohe Priorität zu.
      • Der Standardwert für das Ablaufdatum ist zum Testen in Ordnung. Alternativ können verschiedene Ablauffenster konfiguriert werden.
      • Filter und Attributionszeiträume können zu Testzwecken als Standardeinstellungen beibehalten werden.
    • Optionale Überlegungen:
      • Entwerfen Sie Aggregationsschlüssel, wenn Sie dazu bereit sind.
      • Berücksichtigen Sie die Weiterleitungsstrategie, wenn Sie festlegen, wie Sie mit anderen Analysepartnern zusammenarbeiten möchten.
  3. Fügen Sie Ihrem SDK oder Ihrer App Trigger-Ereignisse registrieren hinzu, um Conversion-Ereignisse aufzuzeichnen.
    • Wichtige Überlegungen:
    • Optionale Überlegungen:
      • Überspringen Sie das Erstellen von Deduplizierungsschlüsseln, bis Sie Genauigkeitstests durchführen.
      • Überspringen Sie das Erstellen von Aggregationsschlüsseln und -werten, bis die Unterstützung für Simulationstests verfügbar ist.
      • Überspringen Sie Weiterleitungen, bis Sie festgelegt haben, wie Sie mit anderen Analysepartnern zusammenarbeiten möchten.
      • Die Triggerpriorität ist für Tests nicht unbedingt erforderlich.
      • Filter können bei ersten Tests wahrscheinlich ignoriert werden.
  4. Testen Sie, ob Quellereignisse für Anzeigen generiert werden und ob Trigger zum Erstellen von Ereignisberichten führen.

Simulationstests

In diesem Abschnitt erfahren Sie, wie Sie testen, wie sich das Verschieben Ihrer aktuellen Conversions in Berichte zu Ereignissen und Zusammenfassungen wahrscheinlich auf Berichts- und Optimierungssysteme auswirkt. Auf diese Weise kannst du mit Wirkungstests beginnen, bevor du die Integration abschließt.

Die Tests werden durch Simulation der Erstellung von Ereignisberichten und aggregierten Berichten basierend auf Ihren bisherigen Conversion-Datensätzen durchgeführt. Die aggregierten Ergebnisse werden dann von einem simulierten Aggregationsserver abgerufen. Diese Ergebnisse können mit den bisherigen Conversion-Zahlen verglichen werden, um zu sehen, wie sich die Genauigkeit der Berichte ändern würde.

Optimierungsmodelle wie die Berechnung der prognostizierten Conversion-Rate können mit diesen Berichten trainiert werden, um die Genauigkeit dieser Modelle im Vergleich zu den Modellen zu vergleichen, die auf aktuellen Daten basieren. Außerdem haben Sie die Möglichkeit, mit verschiedenen Aggregationsschlüsselstrukturen und deren Auswirkungen auf die Ergebnisse zu experimentieren.

  1. Richten Sie die Analysesimulationsbibliothek auf einem lokalen Computer ein.
  2. Lesen Sie in der spec nach, wie Ihre Conversion-Daten formatiert werden müssen, damit sie mit dem simulierten Berichtsgenerator kompatibel sind.
  3. Entwerfen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen.
    • Wichtige Überlegungen:
      • Berücksichtigen Sie die kritischen Dimensionen, die Ihre Kunden oder Partner aggregieren müssen, und konzentrieren Sie Ihre Bewertung darauf.
      • Ermitteln Sie die für Ihre Anforderungen erforderliche Mindestanzahl zusammengefasster Dimensionen und Kardinalitäten.
      • Achten Sie darauf, dass die quell- und triggerseitigen Schlüsselelemente 128 Bit nicht überschreiten.
      • Wenn Ihre Lösungen einen Beitrag zu mehreren Werten pro Triggerereignis beinhalten, achten Sie darauf, die Werte anhand des maximalen Beitragsbudgets, Stufe 1, zu skalieren. Dadurch werden die Störgeräusche minimiert.
      • In diesem Beispiel wird die Einrichtung eines Schlüssels zum Erfassen der Conversion-Gesamtzahl auf Kampagnenebene und eines Schlüssels zum Erfassen aggregierter Kaufwerte auf geografischer Ebene beschrieben.
  4. Führen Sie den Berichtsgenerator aus, um Ereignis- und zusammengefasste Berichte zu erstellen.
  5. Führen Sie die aggregierbaren Berichte über die simulierten Aggregationsserver aus, um Zusammenfassungsberichte zu erhalten.
  6. Führen Sie Dienstprogrammtests durch:
    • Sie können die Gesamtzahl der Conversions aus Berichten auf Ereignisebene und zusammenfassende Berichte mit bisherigen Conversion-Daten vergleichen, um die Genauigkeit der Conversion-Berichte zu ermitteln. Die besten Ergebnisse erzielen Sie, wenn Sie die Berichterstellungstests und -vergleiche für einen breiten, repräsentativen Teil der Werbetreibenden durchführen.
    • Trainieren Sie Ihre Modelle basierend auf Berichtsdaten auf Ereignisebene und möglicherweise zusammengefassten Berichtsdaten neu. Die Genauigkeit mit Modellen vergleichen, die auf bisherigen Trainingsdaten basieren.
    • Probieren Sie verschiedene Batch-Strategien aus und sehen Sie sich an, wie sie sich auf Ihre Ergebnisse auswirken.
      • Wichtige Überlegungen:
      • Pünktlichkeit von Zusammenfassungsberichten zur Anpassung von Geboten
      • Durchschnittliche Häufigkeit von Ereignissen, die auf dem Gerät zugeordnet werden können. Beispiel: Abgesprungene Nutzer, die auf der Grundlage von Daten zu bisherigen Kaufereignissen zurückgekehrt sind.
      • Geräuschpegel. Mehr Batches bedeuten eine kleinere Aggregation und eine kleinere Aggregation bedeutet mehr Rauschen.

Prototyp-Aggregations-Serverzuordnung: Einrichtung

Mit diesen Schritten sorgen Sie dafür, dass Sie aggregierte Berichte zur Quelle und zu den Trigger-Ereignissen erhalten.

  1. Richten Sie den Aggregationsserver ein:
    • Richten Sie Ihr AWS-Konto ein.
    • Melden Sie sich bei Ihrem Koordinator für den Aggregationsdienst an.
    • Richten Sie Ihren Aggregationsserver in AWS mithilfe der bereitgestellten Binärprogramme ein.
  2. Entwerfen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen. Wenn Sie diese Aufgabe im Bereich App-zu-App-Ereignisebene bereits abgeschlossen haben, können Sie diesen Schritt überspringen.
  3. Richten Sie einen Sammlungsserver für aggregierte Berichte ein. Wenn Sie im Bereich für App-zu-App-Ereignisse bereits einen erstellt haben, können Sie ihn wiederverwenden.

Serverzuordnung für Prototyp-Aggregation: Integration

Wenn Sie fortfahren möchten, müssen Sie den Abschnitt Serverzuordnung für Prototyp-Aggregation: Einrichtung oder Prototyp für App-zu-App-Attribution auf Ereignisebene abgeschlossen haben.

  1. Aggregationsschlüsseldaten zur Quelle hinzufügen und Ereignisse auslösen. Dazu müssen wahrscheinlich mehr Daten zum Anzeigenereignis (z. B. die Kampagnen-ID) an Ihr SDK oder Ihre App übergeben werden, damit sie in den Aggregationsschlüssel aufgenommen werden.
  2. Sie erfassen App-zu-App-Berichte aus der Quelle und lösen Ereignisse aus, die Sie mit Aggregationsschlüsseldaten registriert haben.
  3. Testen Sie verschiedene Batchstrategien, während Sie diese aggregierten Berichte über den Aggregationsserver ausführen, und beobachten Sie, wie sie sich auf die Ergebnisse auswirken.

Design mit optionalen Funktionen iterieren

Im Folgenden finden Sie zusätzliche Funktionen, die Sie in Ihre Analyselösung einbinden können.

  1. Wenn Sie einen Schlüssel zur Fehlerbehebung festlegen, erhalten Sie zusammen mit den von der Attribution Reporting API generierten Berichten einen unveränderten Bericht zu einer Quelle oder einem Triggerereignis. Sie können Schlüssel zur Fehlerbehebung verwenden, um Berichte zu vergleichen und Fehler während der Integration zu finden.

Attributionsverhalten anpassen

  1. Attribution für Trigger nach der Installation
    • Diese Funktion kann verwendet werden, wenn Trigger nach der Installation der Attributionsquelle zugeordnet werden müssen, die die Installation ausgelöst hat, auch wenn es andere zulässige Attributionsquellen gibt, die in letzter Zeit aufgetreten sind.
    • So kann es beispielsweise vorkommen, dass ein Nutzer auf eine Anzeige klickt und eine Installation veranlasst. Nach der Installation klickt der Nutzer auf eine andere Anzeige und schließt einen Kauf ab. In diesem Fall möchte das Unternehmen für Anzeigentechnologie, dass der Kauf dem ersten Klick und nicht dem Klick für die erneute Interaktion zugeordnet wird.
  2. Daten in Berichten auf Ereignisebene mithilfe von Filtern optimieren
    • Conversion-Filter können so eingerichtet werden, dass ausgewählte Trigger ignoriert und aus Ereignisberichten ausgeschlossen werden. Da die Anzahl der Trigger pro Attributionsquelle begrenzt ist, können Sie mit den Filtern nur die Trigger einschließen, über die Ihre Ereignisberichte die nützlichsten Informationen enthalten.
    • Filter können auch verwendet werden, um einige Trigger selektiv herauszufiltern und sie effektiv zu ignorieren. Wenn Sie beispielsweise eine auf App-Installationen ausgerichtete Kampagne haben, können Sie herausfiltern, dass Trigger nach der Installation nicht Quellen aus dieser Kampagne zugeordnet werden.
    • Filter können auch verwendet werden, um Triggerdaten basierend auf Quelldaten anzupassen. Beispielsweise kann eine Quelle "product" : ["1234"] angeben, wobei product der Filterschlüssel und 1234 der Wert ist. Jeder Trigger mit dem Filterschlüssel „product“, der einen anderen Wert als „1234“ hat, wird ignoriert.
  3. Benutzerdefinierte Quell- und Triggerpriorität
    • Falls mehrere Attributionsquellen mit einem Trigger verknüpft werden können oder einer Quelle mehrere Trigger zugeordnet werden können, können Sie eine signierte 64-Bit-Ganzzahl verwenden, um bestimmte Quell-/Trigger-Attributionen gegenüber anderen zu priorisieren.

Mit MMPs und anderen Anbietern arbeiten

  1. Weiterleitungen an andere Drittanbieter für Quell- und Trigger-Ereignisse
    • Sie können Weiterleitungs-URLs so festlegen, dass mehrere AdTech-Plattformen eine Anfrage registrieren können. Damit kann die netzwerkübergreifende Deduplizierung bei der Attribution aktiviert werden.
  2. Deduplizierungsschlüssel
    • Wenn ein Werbetreibender mehrere AdTech-Plattformen verwendet, um dasselbe Trigger-Ereignis zu registrieren, kann ein Deduplizierungsschlüssel verwendet werden, um diese wiederholten Berichte voneinander zu unterscheiden. Wenn kein Deduplizierungsschlüssel angegeben ist, können doppelte Trigger für jede Anzeigentechnologie-Plattform eindeutig gemeldet werden.

Plattformübergreifende Analyse verwenden

  1. App- und Web-Attribution (ab Ende des 4. Quartals verfügbar)
    • Unterstützt Anwendungsfälle, bei denen ein Nutzer eine Anzeige in einer App sieht und dann in einem mobilen Browser oder einem App-Browser eine Conversion ausführt oder umgekehrt.