Attribution Reporting API: Integrationsanleitung

Wenn Sie die Dokumentation zu Privacy Sandbox für Android lesen, wählen Sie mit der Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der Sie arbeiten, da die Anleitungen variieren können.

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 Implementierer der Attribution Reporting API einige wichtige allgemeine Aspekte berücksichtigen:

  • Berichte auf Ereignisebene enthalten Conversion-Daten mit geringer Genauigkeit. Eine kleine Anzahl von Conversion-Werten ist ausreichend.
  • Zusammenfassbare Berichte enthalten Conversion-Daten mit höherer Genauigkeit. Ihre Lösungen sollten Aggregationsschlüssel basierend auf Ihren Geschäftsanforderungen und dem 128-Bit-Limit entwerfen.
  • Die Datenmodelle und die Verarbeitung Ihrer Lösung sollten Ratenbeschränkungen für verfügbare Trigger, Zeitverzögerungen beim Senden von Triggerereignissen und Rauschen, das von der API angewendet wird, berücksichtigen.

Dieser Leitfaden soll Ihnen bei der Planung der Integration helfen und bietet einen umfassenden Überblick, der möglicherweise Funktionen enthält, die in der aktuellen Phase der Privacy Sandbox für Android-Entwicklervorschau noch nicht implementiert sind. In diesen Fällen wird eine Zeitachse angegeben.

Auf dieser Seite verwenden wir Quelle für einen Klick oder eine Impression und Trigger für eine Conversion.

Im folgenden Diagramm sehen Sie die verschiedenen Workflow-Optionen für die Attributionsintegration. Abschnitte, die in derselben Spalte aufgeführt sind (grün umrandet), können parallel bearbeitet werden. So kann beispielsweise die Partnerinteraktion gleichzeitig mit der Attributierung auf Ereignisebene von App zu App erfolgen.

Workflow für die Attributionsintegration.
Abbildung 1. Workflow für die Attributionsintegration

Voraussetzungen und Einrichtung

Führen Sie die Schritte in diesem Abschnitt aus, um die Attribution Reporting API besser zu verstehen. Mit diesen Schritten können Sie aussagekräftige Ergebnisse erzielen, wenn Sie die API im Ad-Tech-Ökosystem 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 Updates zur Attribution Reporting API zu erhalten. So bleiben Sie über neue Funktionen auf dem Laufenden, die in zukünftigen Versionen eingeführt werden.

Beispielanwendung einrichten und testen

  1. Wenn Sie mit der Integration beginnen möchten, richten Sie die aktuelle Entwicklervorschau in Android Studio ein.
  2. Richten Sie Mock-Server-Endpunkte für Ereignisregistrierungen und Berichtsübermittlungen ein. Wir haben Mocks bereitgestellt, die Sie in Verbindung 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 den Zeitraum 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 Beispiel-App registriert haben und der festgelegte Zeitraum verstrichen ist, prüfen Sie, ob Sie einen Bericht auf Ereignisebene und einen verschlüsselten aggregierbaren Bericht erhalten haben. Wenn Sie Berichte debuggen müssen, können Sie sie schneller generieren, indem Sie Berichtsjobs erzwingen.
    3. Ergebnisse für die App-zu-App-Attribution ansehen Prüfen Sie, ob die Daten in diesen Ergebnissen sowohl für den Last-Touch- als auch für den Post-Install-Fall den Erwartungen entsprechen.

  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 Orientierungshilfe 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 eine unnötige Duplizierung von Ad-Tech-Plattformen verhindern, die den Zugriff auf mehr Informationen als nötig zu den Aktivitäten des Nutzers ermöglichen würde.

Partnerinteraktion

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

  1. Vereinbaren Sie einen Termin mit Ihren wichtigsten Analysepartnern, um Tests und die Einführung der Attribution Reporting API zu besprechen. Zu den Analysepartnern können Ad-Tech-Netzwerke, SSPs, DSPs, Werbetreibende oder andere Partner gehören, mit denen Sie zusammenarbeiten oder zusammenarbeiten möchten.
  2. Arbeiten Sie mit Ihren Partnern für Messungen zusammen, um Zeitpläne für die Integration festzulegen, von ersten Tests bis zur Einführung.
  3. Klären Sie mit Ihren Analysepartnern, welche Bereiche Sie jeweils bei der Attributionsmodellierung abdecken.
  4. Richten Sie Kommunikationskanäle zwischen den Analysepartnern ein, um Zeitpläne und End-to-End-Tests abzustimmen.
  5. Allgemeine Datenflüsse für Analysepartner entwerfen Wichtige Überlegungen:
    • Wie registrieren Analysepartner Attributionsquellen mit der Attribution Reporting API?
    • Wie registrieren Ad-Tech-Netzwerke Trigger mit der Attribution Reporting API?
    • Wie validiert jede Ad-Tech-Plattform API-Anfragen und gibt Antworten zurück, um Quell- und Triggerregistrierungen abzuschließen?
    • Gibt es Berichte, die mit Partnern außerhalb der Attribution Reporting API geteilt werden müssen?
    • Gibt es weitere Integrationspunkte oder Abstimmungen, die zwischen Partnern erforderlich sind? Müssen Sie und Ihre Partner beispielsweise Conversions deduplizieren oder sich auf Aggregationsschlüssel einigen?
  6. Wenn die App-zu-Web-Attribution infrage kommt, vereinbaren Sie ein Gespräch mit Analysepartnern im Web, um die Entwicklung, das Testen und die Einführung der Attribution Reporting API zu besprechen. Orientieren Sie sich an den Fragen im vorherigen Schritt, wenn Sie Gespräche mit Webpartnern beginnen.

Prototyp für die Attribution auf Ereignisebene zwischen Apps

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 dem Prototyping der Attributierung des Aggregationsservers beginnen können.

  1. Richten Sie einen Erfassungsserver für Ereignisdatensätze ein. Dazu können Sie mit der bereitgestellten Spezifikation einen Mock-Server generieren oder mit dem Beispielservercode einen eigenen Server einrichten.
  2. Fügen Sie Ihrem SDK oder Ihrer App register source event calls hinzu, wenn Anzeigen ausgeliefert werden.
    • Wichtige Aspekte sind:
      • Prüfen Sie, ob Quellereignis-IDs verfügbar sind und korrekt an die API-Aufrufe zur Quellenregistrierung übergeben werden.
      • Prüfen Sie, ob Sie 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, die als hochwertig gelten, eine hohe Priorität zu, z. B. Klicks im Vergleich zu Aufrufen.
      • Der Standardwert für „expiry“ ist für Tests geeignet. Alternativ können verschiedene Ablaufzeiträume konfiguriert werden.
      • Für Tests können die Standardeinstellungen für Filter und Attributionszeiträume beibehalten werden.
    • Optionale Überlegungen:
      • Entwerfen Sie Aggregationsschlüssel, wenn Sie bereit dafür 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 Trigger-Ereignisse registrieren hinzu, um Conversion-Ereignisse aufzuzeichnen.
    • Wichtige Aspekte sind unter anderem:
    • 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 erforderlich.
      • Filter können bei ersten Tests wahrscheinlich ignoriert werden.
  4. Prüfen Sie, ob Quellereignisse für Anzeigen generiert werden und ob Trigger zur Erstellung von Ereignisberichten führen.

Simulationstests

In diesem Abschnitt erfahren Sie, wie Sie die Auswirkungen testen können, die die Umstellung Ihrer aktuellen Conversions auf Ereignis- und aggregierbare Berichte voraussichtlich auf Berichts- und Optimierungssysteme haben wird. So können Sie mit den Impact-Tests beginnen, bevor Sie die Integration abgeschlossen haben.

Beim Testen wird die Erstellung von Ereignis- und aggregierbaren Berichten auf Grundlage Ihrer bisherigen Conversion-Datensätze simuliert. Anschließend werden die aggregierten Ergebnisse von einem simulierten Aggregationsserver abgerufen. Diese Ergebnisse können mit bisherigen Conversion-Zahlen verglichen werden, um zu sehen, wie sich die Genauigkeit der Berichte ändern würde.

Optimierungsmodelle wie Berechnungen 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 können Sie so mit verschiedenen Strukturen für Aggregationsschlüssel experimentieren und sehen, wie sich das auf die Ergebnisse auswirkt.

  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 Generator für simulierte Berichte kompatibel sind.
  3. Entwerfen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen.
    • Wichtige Aspekte sind unter anderem:
      • Berücksichtigen Sie die kritischen Dimensionen, die Ihre Kunden oder Partner benötigen, um Daten zu aggregieren, und konzentrieren Sie Ihre Analyse auf diese.
      • Ermitteln Sie die Mindestanzahl der aggregierten Dimensionen und Kardinalitäten, die für Ihre Anforderungen erforderlich sind.
      • Prüfen Sie, ob die Quell- und Trigger-seitigen Schlüsselkomponenten 128 Bit nicht überschreiten.
      • Wenn Ihre Lösungen mehrere Werte pro Trigger-Ereignis liefern, müssen Sie die Werte an das maximale Budget für Beiträge, L1, anpassen. So lassen sich die Auswirkungen von Rauschen minimieren.
      • Hier finden Sie ein Beispiel, in dem beschrieben wird, wie Sie einen Schlüssel zum Erfassen aggregierter Conversion-Anzahlen auf Kampagnenebene und einen Schlüssel zum Erfassen aggregierter Kaufwerte auf geografischer Ebene festlegen.
  4. Führen Sie den Berichtsgenerator aus, um Ereignis- und aggregierbare Berichte zu erstellen.
  5. Führen Sie die aggregierbaren Berichte über die simulierten Aggregationsserver aus, um Zusammenfassungsberichte zu erhalten.
  6. Tests zur Nützlichkeit durchführen:
    • Vergleichen Sie die Conversion-Gesamtsummen aus Berichten auf Ereignisebene und Zusammenfassungsberichten mit historischen Conversion-Daten, um die Genauigkeit der Conversion-Berichte zu ermitteln. Die besten Ergebnisse erzielen Sie, wenn Sie die Berichterstellungstests und ‑vergleiche mit einem breiten, repräsentativen Teil der Werbetreibenden durchführen.
    • Trainieren Sie Ihre Modelle anhand von Berichtsdaten auf Ereignisebene und möglicherweise auch anhand von zusammenfassenden Berichtsdaten neu. Vergleichen Sie die Genauigkeit mit Modellen, die auf historischen Trainingsdaten basieren.
    • Probieren Sie verschiedene Batching-Strategien aus und sehen Sie sich an, wie sie sich auf Ihre Ergebnisse auswirken.
      • Wichtige Überlegungen sind:
      • Aktualität von Übersichtsberichten zum Anpassen von Geboten
      • Durchschnittliche Häufigkeit von zuordenbaren Ereignissen auf dem Gerät. Beispiel: Inaktive Nutzer kehren auf Grundlage von Daten zu bisherigen Kaufereignissen zurück.
      • Geräuschpegel. Mehr Batches bedeuten eine kleinere Aggregation und eine kleinere Aggregation bedeutet, dass mehr Rauschen angewendet wird.

Attribution des Prototyp-Aggregationsservers: Einrichtung

So können Sie aggregierbare Berichte zu Ihren Quell- und Triggerereignissen erhalten.

  1. Aggregationsserver einrichten:
    • Richten Sie Ihr AWS-Konto ein.
    • Registrieren Sie sich mit Ihrem Koordinator für den Aggregationsdienst.
    • Richten Sie Ihren Aggregationsserver in AWS mit den bereitgestellten Binärdateien ein.
  2. Entwerfen Sie Ihre Aggregationsschlüssel basierend auf den Geschäftsanforderungen. Wenn Sie diese Aufgabe bereits im Abschnitt Ereignisebene für App-zu-App erledigt haben, können Sie diesen Schritt überspringen.
  3. Richten Sie einen Erfassungsserver für aggregierbare Berichte ein. Wenn Sie bereits eine im Abschnitt zu Ereignissen auf App-zu-App-Ebene erstellt haben, können Sie sie wiederverwenden.

Attribution des Prototyp-Aggregationsservers: Integration

Um fortzufahren, müssen Sie den Abschnitt Attribution des Prototyp-Aggregationsservers: Einrichtung oder den Abschnitt Attribution auf Ereignisebene von App zu App** abgeschlossen haben.

  1. Fügen Sie Ihren Quell- und Triggerereignissen Daten für den Aggregationsschlüssel hinzu. Dazu müssen Sie wahrscheinlich mehr Daten zum Anzeigenereignis, z. B. die Kampagnen-ID, in Ihr SDK oder Ihre App einfügen, damit sie in den Aggregationsschlüssel aufgenommen werden.
  2. Erfassen Sie aggregierbare App-zu-App-Berichte aus den Quell- und Triggerereignissen, die Sie mit Aggregationsschlüsseldaten registriert haben.
  3. Testen Sie verschiedene Batching-Strategien, während Sie diese aggregierbaren Berichte über den Aggregationsserver ausführen, und sehen Sie sich an, wie sich das auf Ihre Ergebnisse auswirkt.

Design mit optionalen Funktionen optimieren

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

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

Attributionsverhalten anpassen

  1. Attribution für Trigger nach der Installation
    • Diese Funktion kann verwendet werden, wenn Post-Install-Trigger derselben Attributionsquelle zugeordnet werden müssen, die die Installation ausgelöst hat, auch wenn es andere infrage kommende Attributionsquellen gibt, die erst später aufgetreten sind.
    • Ein Nutzer klickt beispielsweise auf eine Anzeige, die zu einer Installation führt. Nach der Installation klickt der Nutzer auf eine andere Anzeige und tätigt einen Kauf. In diesem Fall soll der Kauf möglicherweise dem ersten Klick und nicht dem Re-Engagement-Klick zugeordnet werden.
  2. Filter verwenden, um die Daten in Berichten auf Ereignisebene zu optimieren
    • Mit Conversion-Filtern können Sie festlegen, dass bestimmte Trigger ignoriert und aus Ereignisberichten ausgeschlossen werden. Da es Limits für die Anzahl der Trigger pro Attributionsquelle gibt, können Sie mit den Filtern nur die Trigger in Ihre Ereignisberichte aufnehmen, die die nützlichsten Informationen liefern.
    • Mit Filtern können Sie auch bestimmte Trigger herausfiltern und so ignorieren. Wenn Sie beispielsweise eine Kampagne mit dem Zielvorhaben „App-Installationen“ haben, möchten Sie möglicherweise verhindern, dass Trigger nach der Installation Quellen aus dieser Kampagne zugeordnet werden.
    • Mit Filtern lassen sich auch Triggerdaten auf Grundlage von Quelldaten anpassen. Eine Quelle kann beispielsweise "product" : ["1234"] angeben, wobei product der Filterschlüssel und 1234 der Wert ist. Alle Trigger mit dem Filterschlüssel „product“ und einem anderen Wert als „1234“ werden ignoriert.
  3. Angepasste Priorität für Quelle und Trigger
    • Wenn mehrere Attributionsquellen einem Trigger zugeordnet werden können oder mehrere Trigger einer Quelle zugeordnet werden können, können Sie eine signierte 64-Bit-Ganzzahl verwenden, um bestimmte Quell- oder Trigger-Attributionen zu priorisieren.

Mit MMPs und anderen zusammenarbeiten

  1. Weiterleitungen an andere Drittanbieter für Quell- und Triggerereignisse
    • Sie können Weiterleitungs-URLs festlegen, damit mehrere Ad-Tech-Plattformen eine Anfrage registrieren können. Damit kann die netzwerkübergreifende Deduplizierung in der Attribution aktiviert werden.
  2. Deduplizierungsschlüssel
    • Wenn ein Werbetreibender mehrere Ad-Tech-Plattformen verwendet, um dasselbe Triggerereignis zu registrieren, kann ein Deduplizierungsschlüssel verwendet werden, um diese wiederholten Berichte zu unterscheiden. Wenn kein Deduplizierungsschlüssel angegeben wird, werden doppelte Trigger möglicherweise an jede Ad-Tech-Plattform als eindeutig gemeldet.

Plattformübergreifende Analyse

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