App Events API

Mit App-Events kannst du Handlungen erfassen, die in deiner mobilen App oder auf deiner Webseite auftreten, etwa App-Installationen und Kauf-Events. Durch das Tracking dieser Events kannst du die Werbeperformance messen und Zielgruppen für das Anzeigen-Targeting erstellen.

Informationen zum Tracking von App-Events für Unternehmens-Messaging findest in der App Events API for Business Messaging in unserer Dokumentation auf der Messenger-Plattform.

So funktioniert’s

Es gibt drei Arten von App-Events:

• Automatisch protokollierte Events – das Facebook-SDK protokolliert automatisch App-Installationen, App-Sitzungen und App-interne Käufe.
• Vordefinierte Events – beliebte Events, die Facebook für dich erstellt hat.
• Eigene Events – Events, die du speziell für deine App erstellst.

Ein App-Event besteht aus drei Teilen:

1. name: Ein erforderlicher String, der das Event beschreibt. Der Name wird im Event-Protokoll angezeigt, wenn das App-Event an Analytics gesendet wird.
2. valueToSum: Ein optionaler Wert, den Analytics zu anderen Additionswerten aus App-Events mit demselben Namen hinzufügt.
3. parameters: Optionale Werte, die in deinem App-Event enthalten sind.

Es sind maximal 1.000 unterschiedliche Event-Namen möglich. Hinweis: Es werden keine neuen Event-Typen protokolliert, wenn du diese Grenze erreichst. Wenn du den Grenzwert überschreitest, kann der Fehler 100 Invalid parameter bei der Protokollierung angezeigt werden. Du kannst aber veraltete Events deaktivieren. Weitere Informationen zu Event-Begrenzungen findest du in den FAQ.

Bevor du beginnst

Voraussetzungen:

• Deine Werbekunden-ID, die Android-Werbe-ID oder die Werbe-ID (IDFA) von einem Apple-Gerät.
• Ein App-Zugriffsschlüssel für Facebook zur Authentifizierung. Speichere deinen App-Zugriffsschlüssel nicht auf dem Client.

App-Installationen

Sende eine POST-Anforderung von deinem Server an den /{app-id}/activities-Endpunkt mit den Parametern application_tracking_enabled und advertiser_tracking_enabled:

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

Wenn der Vorgang erfolgreich verläuft, erhält deine App diese Antwort:

{
  "success": true
}

Achtung

• Du solltest nur eine Installation pro Nutzer*in melden. Dedupliziere IDs möglichst auf ID- und Nutzer*innenebene.

Eine Liste der verfügbaren Parameter findest du in unserem Referenzleitfaden zu Anwendungsaktivitäten.

Werbeanzeigen-Tracking aktivieren

Das Feld advertiser_tracking_enabled gibt an, ob eine Person Werbeanzeigen-Tracking auf ihrem Gerät aktiviert hat. „0“ steht für „Deaktiviert“ und „1“ für „Aktiviert“. Du solltest diese Daten abrufen und an Facebook senden, um zu bestimmen, ob Werbeanzeigen-Tracking zur Optimierung oder für Conversions eingesetzt werden kann. Meta verwendet die Event-Daten (von Partnern über Nutzungsaktivitäten außerhalb von Meta) in Übereinstimmung mit seiner Datenrichtlinie unter anderem zur Erstellung von Anzeigenberichten, zur Betrugserkennung und als Grundlage bei der Gestaltung und Verbesserung unserer Produkte (einschließlich unserer Anzeigenauslieferungsprodukte). Wir untersagen jedoch die Verwendung von personenbezogenen Daten zur Personalisierung der Anzeigen für eine*n Nutzer*in. Bei Geräten mit älteren Versionen als iOS 6 sollte dieser Parameter standardmäßig „1“ lauten.

Unter Apple, AdSuppport-Referenz findest du Informationen zum Abrufen des Tracking-Status eines*einer Nutzer*in.

Das folgende Code-Schnipsel zeigt, wie du den Wert des Flags für Tracking-Aktivierung abrufst.

Die aktuelle Einstellung des Flags für Tracking-Aktivierung erhältst du aus der Eigenschaft Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

Werbeanzeigen-Tracking deaktivieren

Jede App kann eine Einstellung integrieren, mit der Nutzer*innen das Anzeigen-Tracking in dieser App ausschalten können. Facebook fordert seine Partner auf, diese Option in ihr SDK aufzunehmen und die Auswahl des*der Nutzer*in zusammen mit dem Installations- oder Conversion-Event an Facebook zu melden. Facebook nutzt das Installations- oder Conversion-Event für Anzeigenberichte, schränkt aber seine Nutzung bei der Anzeigenoptimierung ein. Die Einstellung des*der Nutzer*in muss bei allen App-Launches gleich bleiben.

Conversion-Events

Sende eine POST-Anforderung an den /{app-id}/activities-Endpunkt, wobei der event auf CUSTOM_APP_EVENTS festgelegt ist, und lege advertiser_tracking_enabled für jedes einzelne Event fest. Der Parameter advertiser_id oder attribution ist erforderlich.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

Wenn der Vorgang erfolgreich verläuft, erhält deine App diese Antwort:

{
  "success": true
}

Attribution

Der attribution-Endpunkt gibt Installationen und Conversions basierend auf Klicks zurück, die innerhalb von 28 Tagen für eine Werbeanzeige angefallen sind. Der Werbeanzeigenmanager verwendet eine 1-Tages-Ansicht durch eine 28-Tage-Klickattribution und zeigt Insights basierend auf Impressions- oder Klickzeit anstelle von Installations- oder Conversion-Zeit an. Das ist vor allem dann wichtig, wenn du deine Berichte mit Berichten des Facebook-Werbeanzeigenmanagers vergleichst. Zusätzlich zu den standardmäßigen App-Event-Ansprüchen bei Anzeigenklicks solltest du auch die folgenden Szenarien berücksichtigen:

• View-Through-Attributionsbeanspruchungen: Durch Festlegen von consider_views=TRUE werden Attributionsdaten für Installationen zurückgegeben, die innerhalb eines Tages nach einer Werbeimpression stattgefunden haben, sofern das Kontenübersichtkonto nicht innerhalb von 28 Tagen auf eine Werbeanzeige geklickt hat. Die zurückgegebene Antwort lautet is_view_through=TRUE und click_time wird durch view_time ersetzt. Alle anderen Attributionen sind die gleichen wie bei Klick-Attributionsdaten für Werbeanzeigen.

• Kampagnenübergreifende Beanspruchungen: Werbetreibende können die Performance aller Werbeanzeigen tracken, die zu einem App-Event geführt haben. Facebook sendet Beanspruchungen für Events von Werbekampagnen, solange das Kampagnenziel nicht auf „Mobile App-Installationen“ oder „Interaktionen mit der mobilen App“ gesetzt ist. Diese Daten werden nur angezeigt, wenn der Werbetreibende die App zum Feld „Tracking von mobilen App-Events“ seiner Werbeanzeige hinzugefügt hat.

• Anwendungsfall: Wenn der*die Kund*in die Installationen aufgrund von Klicks auf eine Page Post Ad oder eine Website Ad aufzeichnen möchten, die Nutzer*innen zu einer mobilen Webseite leiten, können sie dazu den Werbeanzeigenmanager verwenden. Facebook beansprucht dann die relevanten App-Installationen.

• Geräteübergreifende Beanspruchungen: Werbetreibende mit Apps auf mehreren Plattformen können Daten zu App-Installationen ansehen, die durch Werbeanzeigen auf diesen verschiedenen Plattformen verursacht werden.

• Anwendungsfall: Ein*e Nutzer*in klickt auf eine iPhone-Werbeanzeige für eine App und installiert die App dann auf dem iPad. Wir können dann die App-Installation auf dem iPad unabhängig vom Anzeigen-Targeting der iPhone-Werbeanzeige zuordnen.

Erweiterter Abgleich

Mithilfe des erweiterten Abgleichs kannst du Kund*innendaten an Facebook senden. Wir verwenden diese Daten, um genauer festzustellen, welches Kontenübersichtskonto als Reaktion auf deine Anzeige eine Aktion durchgeführt hat. Anhand dieser Daten kann Facebook Conversion-Events mit deinen Kund*innen abgleichen, um deine Anzeigen zu optimieren und größere Zielgruppen für das Remarketing zu erstellen.

Sende eine POST-Anforderung an den /{app-id}/activities-Endpunkt, wobei der ud-Parameter auf Kund*innendaten wie zum Beispiel die E-Mail-Adresse oder Telefonnummer festgelegt ist. Alle Kund*innendaten müssen gehasht werden. Andernfalls werden sie von Facebook ignoriert. Lege advertiser_tracking_enabled für jedes einzelne Event fest.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

Wenn der Vorgang erfolgreich verläuft, erhält deine App diese Antwort:

{
  "success": true
}

Alle Nutzungsdaten müssen vor dem Senden an Facebook mit SHA256 gehasht werden. Facebook ignoriert nicht gehashte Daten.

Deduplizierung

Wir wenden dieselbe Deduplizierungsfunktion für App-Events an, die auch für Web-Events verwendet wird. Die Deduplizierungslogik basiert auf den Feldern event_id und event_name. Der event_id-Parameter ist eine ID, die ähnliche Events eindeutig voneinander unterscheiden kann. Ungenaue Event-IDs können zu einer fehlerhaften Deduplizierung deiner Conversion führen. Dies kann sich auf das Conversion-Reporting und die Kampagnenperformance auswirken.

Erweiterte Geräteinformationen

Sende Geräteinformationen wie die Breite und Höhe des Bildschirms in deinem App-Event-Aufruf mithilfe von /{app-id}/activities?extinfo. Werte werden durch Komma getrennt und müssen in der im /application/activites-Referenzleitfaden angegebenen Reihenfolge vorliegen. Bei Verwendung von extinfo sind alle Werte erforderlich.

• version muss für Android a2 sein.
• version muss für iOS i2 sein.

Referenz

• ApplicationActivities-Parameter
• Android-Entwicklungsdokumentation – Kennzahlen anzeigen
• Android-Entwicklungsdokumentation – externe Speicherung
• Apple-Entwicklungsdokumentation – Kennzahlen anzeigen
• Apple-Entwicklungsdokumentation – externe Speicherung
• Apple-Entwicklungsdokumentation – Bildschirmgröße

Mobile Cookies abrufen

Wir empfehlen dir, App-Events mit einer advertiser_id zu verknüpfen. Bei Android-Geräten und iOS-Geräten vor iOS 6 kannst du aber auch den attribution-Parameter verwenden, der auf das mobile Cookie des Geräts festgelegt ist.

Hinweis: Mobile Cookies werden nicht von Nutzer*innen- oder Geräteattributen abgeleitet. Diese Cookies sind nicht beständig und sollten häufig aktualisiert werden. Verwende mobile Cookies nicht für Retargeting-Anzeigen.

Android

Das Cookie ist ein alphanumerischer Zufallsstring mit 22 Zeichen.

Rufe die Facebook-Attributions-ID mithilfe von ContentProvider ab:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Du solltest auch die Advertising ID deiner Android-App abrufen.

iOS

Das mobile Cookie wird mit CFUUIDCreateString von Facebook-iOS-Apps erstellt und ist eine 128-Bit-UUID-String-Darstellung.

Rufe sowohl die Cookie-ID als auch den IDFA ab und sende sie als ID an Facebook:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

X-Forwarded-For-HTTP-Header

Wenn POST-Anforderungen von einem zentralen Ort wie einem Server oder Proxy getätigt werden – also im Wesentlichen ein Server-zu-Server-Aufruf – ist der X-Forwarded-For-HTTP-Header erforderlich, um richtige Standort- und Geräteinformationen sicherzustellen. Sende die IP-Adresse des Geräts im IPv4- oder IPv6-Format über den X-Forwarded-For-HTTP-Headerparameter in jeder gesendeten App-Event-Anfrage. So können wir die advertiser_id der richtigen IP-Adresse zuordnen und dann in unserer Plattform verwenden.

Beispiel mit IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

Beispiel mit IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Testen

1. Rufe den Events Manager auf.
2. Klicke links auf der Seite auf das Symbol „Datenquellen“.
3. Wähle den Namen und die ID deiner Daten aus.
4. Klicke auf „Events testen“ und wähle Kanal als App aus.
5. Sende eine AE-API-Anfrage mit dem Graph API Tool.
6. Deine Interaktionen werden kurz darauf im Tab „Events testen“ angezeigt.

Abweichungen

Falls ein*e Kund*in die Berichte eines Mobile Measurement Partners mit Facebook-Berichten vergleicht und Abweichungen feststellt, sollten die folgenden Aspekte geprüft werden:

Wenn Facebook weniger Installationen als der MMP meldet:

• Ist das FB-SDK richtig integriert?
• Verwendet der*die Kund*in die falsche App-ID?

Wenn Facebook mehr Installationen als der MMP meldet:

• Stimmen die Attributionsfenster überein? Facebook hat im Allgemeinen ein größeres Attributionsfenster als die meisten Mobile Measurement Partner.
• Ist das MMP-SDK richtig integriert?
• Verwendet der*die Kund*in die falsche App-ID?
• Bezieht sich die Abweichung nur auf iOS 7? Empfängt der MMP die Werbe-ID von Apple (IDFA) vom Gerät und übergibt er sie korrekt an FB?

Referenz

Anwendungsaktivitäten (erweiterte Informationen)

Im /application/activites-Referenzleitfaden findest du weitere Informationen zu erweiterten App-Informationen.

Nutzungsdatenparameter

Name des vordefinierten Events

Standard-Event-Parameter

Siehe auch

• App-Events
• Best Practices für App-Events
• Behandeln von Fehlern
• Einhaltung der DSGVO
• Werbeanzeigenmanager von Facebook
• Facebook App-Dashboard