Attribution Reporting API: Integrationsanleitung

Wählen Sie in der Dokumentation zur Privacy Sandbox für Android mit der Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der Sie arbeiten. Die Anleitungen können variieren.

Die Attribution Reporting API wurde entwickelt, um wichtige Anwendungsfälle für die Attributions- und Conversion-Analyse in Apps und im Web zu unterstützen, ohne dass dienstleisterübergreifende Nutzerkennungen erforderlich sind. Im Vergleich zu gängigen Designs sollten die Implementierer der Attribution Reporting API einige wichtige allgemeine Aspekte berücksichtigen:

  • Berichte auf Ereignisebene enthalten Low-Fidelity-Conversion-Daten. Eine kleine Anzahl von Conversion-Werten funktioniert gut.
  • Aggregierbare Berichte enthalten Conversion-Daten mit höherer Genauigkeit. Die Aggregationsschlüssel Ihrer Lösungen sollten auf Grundlage Ihrer Geschäftsanforderungen und der 128-Bit-Grenze entworfen werden.
  • Die Datenmodelle und die Verarbeitung Ihrer Lösung sollten Geschwindigkeitslimits für verfügbare Trigger, Zeitverzögerungen beim Senden von Triggerereignissen und Rauschen berücksichtigen, das von der API angewendet wird.

Dieser Leitfaden bietet einen umfassenden Überblick, der auch Funktionen enthalten kann, die in der aktuellen Version der Privacy Sandbox in der Android-Entwicklervorschau noch nicht implementiert sind. In diesen Fällen erhalten Sie eine Zeitleiste.

Auf dieser Seite wird Quelle für einen Klick oder eine Wiedergabe und Trigger für eine Conversion verwendet.

Im folgenden Diagramm sind die verschiedenen Workflowoptionen für die Attributionsintegration dargestellt. Abschnitte, die in derselben Spalte aufgeführt sind (grün umkreist), können parallel bearbeitet werden. So können Sie beispielsweise die Interaktionen mit Partnern gleichzeitig mit der App-zu-App-Attribution auf Ereignisebene auswerten.

Workflow-Diagramm für die Attributionsintegration

Abbildung 1. Der Attributions-Integrations-Workflow

Voraussetzungen und Einrichtung

Führen Sie die Schritte in diesem Abschnitt aus, um die Attribution Reporting API besser kennenzulernen. So können Sie aussagekräftige Ergebnisse erzielen, wenn Sie die API im AdTech-System 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. Melden Sie sich an, um aktuelle Informationen zur Attribution Reporting API zu erhalten. So bleiben Sie über neue Funktionen in zukünftigen Releases auf dem Laufenden.

Beispielanwendung einrichten und testen

  1. Wenn Sie mit der Integration beginnen möchten, richten Sie die aktuelle Entwicklervorschau in Android Studio ein.
  2. Mock-Serverendpunkte für Ereignisregistrierungen und Berichtsübermittlungen einrichten Wir haben Mockups bereitgestellt, die Sie in Kombination mit online verfügbaren Tools verwenden können.
  3. Laden Sie den Code in unserer Beispiel-App herunter und führen Sie ihn aus, um sich mit der Registrierung von Quellen und Triggern vertraut zu machen.
    1. Legen Sie das Zeitfenster für das Senden von Berichten fest. Die API unterstützt Zeitfenster von 2 Tagen, 7 Tagen oder einen benutzerdefinierten Zeitraum zwischen 2 und 30 Tagen.
    2. Nachdem Sie Quellen und Trigger registriert haben, indem Sie die Beispiel-App ausgeführt und verwendet haben, und der festgelegte Zeitraum verstrichen ist, prüfen Sie, ob Sie einen Bericht auf Ereignisebene und einen verschlüsselten aggregierten Bericht erhalten haben. Wenn Sie Berichte beheben müssen, können Sie sie schneller erstellen, indem Sie Berichtsjobs erzwingen.
    3. Prüfen Sie die Ergebnisse für die App-zu-App-Attribution. Prüfen Sie, ob die Daten in diesen Ergebnissen sowohl für den letzten Touchpoint als auch für den Fall nach der Installation wie erwartet sind.

  4. Nachdem Sie ein Gefühl dafür bekommen haben, wie die Client-API und der Server zusammenarbeiten, können Sie die Beispiel-App als Beispiel für Ihre eigene Integration verwenden. Richten Sie Ihren eigenen Produktionsserver ein und fügen Sie Ihren Apps Aufrufe zur Ereignisregistrierung hinzu.

Vor der Einrichtung

Registrieren Sie Ihre Organisation für die Privacy Sandbox für Android. Diese Registrierung soll unnötige Duplikate von Anzeigentechnologie-Plattformen verhindern, die den Zugriff auf mehr Informationen als nötig über die Aktivitäten der Nutzer ermöglichen würden.

Partner engagement

AdTech-Partner (MMP/SSP/DSP) entwickeln häufig integrierte Attributionslösungen. Die Schritte in diesem Abschnitt helfen Ihnen, die Zusammenarbeit mit Ihren AdTech-Partnern erfolgreich zu gestalten.

  1. Vereinbaren Sie ein Gespräch mit Ihren wichtigsten Analysepartnern, um die Tests und die Einführung der Attribution Reporting API zu besprechen. Partner für Analyselösungen können Werbetechnologienetzwerke, SSPs, DSPs, Werbetreibende oder andere Partner sein, mit denen Sie derzeit zusammenarbeiten oder mit denen Sie zusammenarbeiten möchten.
  2. Erarbeiten Sie gemeinsam mit Ihren Partnern für Analysen Zeitpläne für die Integration, vom ersten Test bis zur Einführung.
  3. Klären Sie mit Ihren Analysepartnern, welche Bereiche Sie jeweils im Attributionsdesign abdecken.
  4. Richten Sie Kommunikationskanäle zwischen den Analysepartnern ein, um Zeitpläne und End-to-End-Tests zu synchronisieren.
  5. Erstellen Sie allgemeine Datenflüsse für alle Anbieter von Analysetools. Wichtige Überlegungen sind:
    • Wie registrieren Analysepartner Attributionsquellen bei der Attribution Reporting API?
    • Wie registrieren AdTech-Netzwerke Trigger bei der Attribution Reporting API?
    • Wie validieren die einzelnen Anbieter von Anzeigentechnologien API-Anfragen und geben Antworten zurück, um die Registrierung von Quellen und Triggern abzuschließen?
    • Gibt es Berichte, die außerhalb der Attribution Reporting API für Partner freigegeben werden müssen?
    • Gibt es weitere Integrationspunkte oder Abstimmungen, die für alle Partner erforderlich sind? Müssen Sie und Ihre Partner beispielsweise an der Deduplizierung von Conversions arbeiten oder sich auf Aggregationsschlüssel einigen?
  6. Wenn die App-zu-Web-Attribution zutrifft, vereinbaren Sie ein Gespräch mit Ihren Web-Analysepartnern, um das Design, die Tests und die Einführung der Attribution Reporting API zu besprechen. Denken Sie an die Fragen im vorherigen Schritt, wenn Sie mit Webpartnern sprechen.

App-zu-App-Attribution auf Ereignisebene als Prototyp

In diesem Abschnitt erfahren Sie, wie Sie eine grundlegende 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 dem Prototyping der Aggregationsserver-Attribution beginnen können.

  1. Richten Sie einen Erfassungsserver für Ereigniseinträge ein. Sie können dazu die vordefinierte Spezifikation verwenden, um einen Mock-Server zu generieren, oder Ihren eigenen Server mit dem Beispielservercode einrichten.
  2. Fügen Sie Ihrem SDK oder Ihrer App Ereignisanrufe zum Registrieren der Quelle hinzu, wenn Anzeigen ausgeliefert werden.
    • Wichtige Überlegungen sind:
      • Sorgen Sie dafür, dass Quellereignis-IDs verfügbar sind und korrekt an die API-Aufrufe zur Quellenregistrierung übergeben werden.
      • Sie müssen auch ein „InputEvent“ übergeben können, um Klickquellen zu registrieren.
      • Legen Sie fest, wie Sie die Quellpriorität für verschiedene Ereignistypen konfigurieren. Weisen Sie beispielsweise Ereignissen mit hohem Wert eine hohe Priorität zu, z. B. Klicks gegenüber Aufrufen.
      • Der Standardwert für „expiry“ ist für Tests in Ordnung. Alternativ können unterschiedliche Ablaufzeiträume konfiguriert werden.
      • Filter und Attributionsfenster können für den Test bei den Standardeinstellungen belassen werden.
    • Optionale Überlegungen:
      • Erstellen Sie Aggregationsschlüssel, wenn Sie bereit sind.
      • Berücksichtigen Sie Ihre Weiterleitungsstrategie, wenn Sie festlegen, wie Sie mit anderen Analysepartnern zusammenarbeiten möchten.
  3. Fügen Sie Ihrem SDK oder Ihrer App Ereignisse zum Registrieren von Triggern hinzu, um Conversion-Ereignisse zu erfassen.
    • Wichtige Überlegungen sind:
    • Optionale Überlegungen:
      • Erstellen Sie Deduplizierungsschlüssel erst, wenn Sie Genauigkeitstests durchführen.
      • Erstellen Sie keine Aggregationsschlüssel und ‑werte, bis die Unterstützung für Simulationstests verfügbar ist.
      • Überspringen Sie die 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 für die ersten Tests wahrscheinlich ignoriert werden.
  4. Prüfen Sie, ob für Anzeigen Quell-Ereignisse generiert werden und ob Trigger zum Erstellen von Ereignisberichten führen.

Simulationstests

In diesem Abschnitt erfahren Sie, wie Sie die Auswirkungen der Umstellung Ihrer aktuellen Conversions auf Ereignis- und aggregierbare Berichte auf die Berichts- und Optimierungssysteme testen. So können Sie mit den Auswirkungen der Änderungen experimentieren, bevor Sie die Integration abschließen.

Dabei wird die Generierung von Ereignis- und aggregierbaren Berichten basierend auf Ihren bisherigen Conversion-Einträgen simuliert und die aggregierten Ergebnisse werden dann von einem simulierten Aggregationsserver abgerufen. Diese Ergebnisse können mit bisherigen Conversion-Zahlen verglichen werden, um zu sehen, wie sich die Berichtsgenauigkeit ändern würde.

Optimierungsmodelle wie die Berechnung der prognostizierten Conversion-Rate können anhand dieser Berichte trainiert werden, um die Genauigkeit dieser Modelle mit denen 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 Measurement Simulation Library auf einem lokalen Computer ein.
  2. In der Spezifikation erfahren Sie, wie Ihre Conversion-Daten formatiert sein müssen, damit sie mit dem simulierten Berichtsgenerator kompatibel sind.
  3. Erstellen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen.
    • Wichtige Aspekte sind:
      • Berücksichtigen Sie die wichtigen Dimensionen, die Ihre Kunden oder Partner zusammenfassen müssen, und konzentrieren Sie sich bei der Bewertung darauf.
      • Bestimmen Sie die Mindestanzahl der zusammengefassten Dimensionen und Kardinalitäten, die für Ihre Anforderungen erforderlich sind.
      • Die Schlüsselteile auf Quell- und Triggerseite dürfen 128 Bit nicht überschreiten.
      • Wenn Ihre Lösungen zu mehreren Werten pro Triggerereignis beitragen, müssen Sie die Werte anhand des maximalen Beitragsbudgets (L1) skalieren. So lassen sich die Auswirkungen von Rauschen minimieren.
      • In diesem Beispiel wird gezeigt, wie Sie einen Schlüssel zum Erfassen aggregierter Conversion-Anzahl auf Kampagnenebene und einen Schlüssel zum Erfassen aggregierter Kaufwerte auf geografischer Ebene einrichten.
  4. Mit dem Berichtsgenerator können Sie Ereignisberichte und aggregierbare Berichte erstellen.
  5. Führen Sie die aggregierbaren Berichte über die simulierten Aggregationsserver aus, um Zusammenfassungsberichte zu erhalten.
  6. Nützlichkeitstests durchführen:
    • Vergleichen Sie die Conversion-Summen aus Berichten auf Ereignisebene und Zusammenfassungsberichten mit bisherigen Conversion-Daten, um die Genauigkeit der Conversion-Berichte zu ermitteln. Die besten Ergebnisse erzielen Sie, wenn Sie die Berichtstests und ‑vergleiche auf einen breiten, repräsentativen Teil der Werbetreibenden ausweiten.
    • Trainieren Sie Ihre Modelle anhand von Berichtsdaten auf Ereignisebene und gegebenenfalls auch anhand von Daten aus Zusammenfassungsberichten neu. Vergleichen Sie die Genauigkeit mit Modellen, die auf bisherigen Trainingsdaten basieren.
    • Probieren Sie verschiedene Batching-Strategien aus und sehen Sie, wie sich diese auf Ihre Ergebnisse auswirken.
      • Wichtige Überlegungen sind:
      • Aktualität von Zusammenfassungsberichten zur Anpassung von Geboten
      • Durchschnittliche Häufigkeit der zurechenbaren Ereignisse auf dem Gerät. Beispielsweise können Sie Nutzer, die sich nicht mehr aktiv für Ihre Marke interessieren, anhand von Daten zu bisherigen Kaufereignissen wieder ansprechen.
      • Geräuschpegel Mehr Batches bedeuten eine kleinere Aggregation und eine kleinere Aggregation bedeutet, dass mehr Rauschen angewendet wird.

Aggregationsserver-Attribution für Prototypen: Einrichtung

So können Sie aggregierbare Berichte zu Ihren Quell- und Triggerereignissen 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 mit den bereitgestellten Binärdateien ein.
  2. Erstellen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen. Wenn Sie diese Aufgabe bereits im Abschnitt App-zu-App-Ereignisse auf Ereignisebene erledigt haben, können Sie diesen Schritt überspringen.
  3. Einen Sammlungsserver für aggregierbare Berichte einrichten Wenn Sie bereits eine im Abschnitt Ereignisebene für App-zu-App-Interaktionen erstellt haben, können Sie sie wiederverwenden.

Aggregationsserver-Attribution für Prototyp: Integration

Damit Sie fortfahren können, müssen Sie den Abschnitt Attribution für den Prototyp-Aggregationsserver: Einrichtung oder den Abschnitt Attribution auf Ereignisebene für den Prototyp von App zu App abgeschlossen haben.**

  1. Fügen Sie Ihrer Quelle Daten zu Aggregationsschlüsseln hinzu und lösen Sie Ereignisse aus. Dazu müssen Sie wahrscheinlich mehr Daten zum Anzeigenereignis, z. B. die Kampagnen-ID, an Ihr SDK oder Ihre App übergeben, um sie in den Aggregationsschlüssel aufzunehmen.
  2. Erfassen Sie Berichte, die zwischen Apps aggregiert werden können, aus der Quelle und lösen Sie Ereignisse aus, die Sie mit Daten zu Aggregationsschlüsseln registriert haben.
  3. Testen Sie verschiedene Batch-Strategien, wenn Sie diese aggregierbaren Berichte über den Aggregationsserver ausführen, und sehen Sie sich an, wie sich diese auf Ihre Ergebnisse auswirken.

Design mit optionalen Funktionen iterieren

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

  1. Wenn Sie einen Debug-Schlüssel festlegen, erhalten Sie neben den Berichten, die von der Attribution Reporting API generiert werden, einen unveränderten Bericht zu einem Quell- oder Triggerereignis. Mit Debug-Schlüsseln können Sie Berichte vergleichen und während der Integration Fehler finden.

Attributionsverhalten anpassen

  1. Attribution für Trigger nach der Installation
    • Diese Funktion kann verwendet werden, wenn Trigger nach der Installation derselben Attributionsquelle zugeordnet werden müssen, die zur Installation geführt hat, auch wenn es andere infrage kommende Attributionsquellen gibt, die vor Kurzem verwendet wurden.
    • Ein Nutzer klickt beispielsweise auf eine Anzeige, die zu einer Installation führt. Nach der Installation klickt der Nutzer auf eine weitere Anzeige und tätigt einen Kauf. In diesem Fall möchte das AdTech-Unternehmen möglicherweise, dass der Kauf dem ersten Klick und nicht dem Klick nach der erneuten Interaktion zugeordnet wird.
  2. Daten in Berichten auf Ereignisebene mithilfe von Filtern optimieren
    • Mit Conversion-Filtern können Sie ausgewählte Trigger ignorieren und aus Ereignisberichten ausschließen. Da die Anzahl der Trigger pro Attributionsquelle begrenzt ist, können Sie mithilfe der Filter nur die Trigger in Ihre Ereignisberichte aufnehmen, die die nützlichsten Informationen enthalten.
    • Mit Filtern können Sie auch bestimmte Trigger selektiv herausfiltern und so effektiv ignorieren. Wenn Sie beispielsweise eine Kampagne auf App-Installationen ausgerichtet haben, können Sie ausschließen, dass Trigger nach der Installation Quellen aus dieser Kampagne zugeordnet werden.
    • Mit Filtern können Sie Triggerdaten auch anhand von Quelldaten anpassen. Eine Quelle kann beispielsweise "product" : ["1234"] angeben, wobei Produkt der Filterschlüssel und 1234 der Wert ist. Trigger mit dem Filterschlüssel „product“, der einen anderen Wert als „1234“ hat, werden ignoriert.
  3. Benutzerdefinierte Priorität für Quelle und Trigger
    • Wenn einem Trigger mehrere Attributionsquellen oder einer Quelle mehrere Trigger zugeordnet werden können, können Sie eine signierte 64-Bit-Ganzzahl verwenden, um bestimmte Attributionen von Quellen/Triggern gegenüber anderen zu priorisieren.

Mit MMPs und anderen Anbietern zusammenarbeiten

  1. Weiterleitungen an andere Drittanbieter für Quell- und Triggerereignisse
    • Sie können Weiterleitungs-URLs festlegen, damit mehrere AdTech-Plattformen eine Anfrage registrieren können. So lässt sich die netzübergreifende Deduplizierung bei der Attribution aktivieren.
  2. Deduplizierungsschlüssel
    • Wenn ein Werbetreibender dasselbe Triggerereignis über mehrere Anzeigentechnologie-Plattformen registriert, kann ein Deduplizierungsschlüssel verwendet werden, um diese wiederholten Berichte zu unterscheiden. Wenn kein Schlüssel zur Deduplizierung angegeben wird, werden doppelte Trigger möglicherweise als eindeutig an jede AdTech-Plattform zurückgemeldet.

Plattformübergreifende Analyse verwenden

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