Conversions API für App-Events

Mit der Conversions API können Werbetreibende Web-Events, App-Events, Events in physischen Stores und Business-Messaging-Events über einen einzigen Endpunkt statt über mehrere Quellen an Meta senden. Diese Konsolidierung vereinfacht die technischen Anforderungen für Werbetreibende. Außerdem wird mit der Verwendung von Datensätzen eine umfassendere Ansicht im Meta Events Manager erstellt.

Diese Dokumentation enthält eine Anleitung zur Integration von App-Events in die Conversions API.

Voraussetzungen

1. Datensatz

Über die Conversions API gesendete App-Events müssen mit einem Datensatz verbunden sein.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

Du kannst den GET-Aufruf unter https://graph.facebook.com /v16.0/{ads-pixel-id}/is_consolidated_container tätigen, um festzustellen, ob der Datensatz des Werbetreibenden konsolidiert und somit zur Weitergabe von App-Events über die Conversions API autorisiert ist.

2. Berechtigungen

Um als Werbetreibender eine direkte Integration zu implementieren, befolge bitte die Anweisungen hier zu den Voraussetzungen und Berechtigungen.
Für die Implementierung einer Partnerplattform-Integration befolge bitte die Anweisungen hier zu den Voraussetzungen und Berechtigungen.

Konfiguration

Senden von App-Events an die Conversions API

a. Verlinken von Datensatz-ID und App-ID

Im Events Manager gibt es zwei Möglichkeiten, deine App mit einem Datensatz zu verlinken:

Wähle den Tab „Datenquellen“ aus, suche den Tab „Einstellung“ deiner App und führe die Verlinkung durch.
Wähle den Tab „Datenquellen“ im Tab „Übersicht“ deiner App aus und verwende den Button „Link zum Datensatz“ im Bereich „Alle Aktivitäten“.

Sobald du die Verlinkung abgeschlossen hast, enthält der Datensatz die verbundene App.

b. Erforderliche Felder

Du kannst hier auf den aktuellen Satz Parameter verweisen, der über die Conversions API gesendet werden kann. Zum Senden von App-Events können die folgenden server_event Felder im Payload geteilt werden:

Der Parameter action_source muss den Wert app für App-Events enthalten.
Die event_id ist für die Deduplizierungs-Einrichtung erforderlich.
app_data fields
user_data fields
custom_data fields

App-Datenfelder

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

Parameter für Kund*inneninformationen

Parameter	Beschreibung
`anon_id` String	Nicht hashen. Deine Installations-ID. Dieses Feld stellt individuelle Anwendungs-Installationsinstanzen dar.
`madid` String	Nicht hashen. Deine Mobile Advertiser ID, die Advertising ID von einem Android-Gerät oder den Advertising Identifier (IDFA) von einem Apple-Gerät.

Selbstdefinierte Daten

Parameter	Beschreibung
`description` String	Optional. String, Event-Beschreibung, selbstdefiniert.
`level` String	Optional. String, Level für ein Spiel, selbstdefiniert.
`max_rating_value`	Optional. Lang, Oberer Grenzwert einer Bewertungsskala, z. B. 5 bei einer Skala mit 5 Sternen.
`success` Boolescher Wert	Optional. `1` für Ja, `0` für Nein, selbstdefiniert.

Insgesamt sind für die App-Events, die mit der Conversions API geteilt werden, die folgenden Datenparameter erforderlich:

action_source: Muss auf „App“ eingestellt sein. (Indem du die Conversions API verwendest, versicherst du, dass der Parameter action_source nach bestem Wissen und Gewissen richtig ist.)
event_id: Für die Einrichtung der Deduplizierung erforderlich, siehe Details unter „Einrichten der Deduplizierung für mehrere Kanäle“.
advertiser_tracking_enabled
application_tracking_enabled
extinfo

Nachstehend findet du ein Beispiel für extinfo. Stelle sicher, dass alle nachstehenden Unterparameter angegeben sind und in sequentieller Reihenfolge aufgeführt werden. Falls etwas fehlt, füge einen leeren String als Platzhalter ein.

Name des Unterparameters	Erforderlich	Datentyp	Beispiel
extinfo-Version	Ja	String	`i2` (Version muss für Android a2 und für iOS i2 sein)
App-Paketname	Nein	String	`com.facebook.sdk.samples.hellofacebook`
Kurzversion	Nein	String	`1.0`
Lange Version	Nein	String	`1.0 long`
Betriebssystemversion	Ja	String	`13.4.1`
Gerätemodellname	Nein	String	`iPhone5,1`
Ländereinstellung	Nein	String	`En_US`
Zeitzone Abk.	Nein	String	`PDT`
Anbieter	Nein	String	`AT&T`
Bildschirmbreite	Nein	String	`320`
Bildschirmhöhe	Nein	String	`568`
Bildschirmdichte	Nein	String	`2`
CPU-Core	Nein	String	`2`
Größe des externen Speichers	Nein	String	`13`
freier Speicherplatz in externem Speicher	Nein	String	`8`
Zeitzone für das Gerät	Nein	String	`USA/New York`

c. Einrichten der Deduplizierung für mehrere Kanäle

Der Deduplizierungsmechanismus ist erforderlich, um den duplizierten Event-Traffic zwischen der Conversions API-Integration und deinen anderen bestehenden Integrationen mit App Events, einschließlich SDK, MMPs und App Events API, zu entfernen.

Für App-Events wenden wir dieselbe Deduplizierungsfunktion an wie für Web-Events. Die Logik nutzt die auf den Feldern event_id und event_name basierte Deduplizierung (Conversions API und SDK / App Events API-Events, die über dieselbe event_id verfügen). Der event_id-Parameter ist eine ID zur eindeutigen Unterscheidung ähnlicher Events. Ungenaue Event-IDs können zu einer fehlerhaften Deduplizierung deiner Conversion führen. Dies kann sich auf das Conversion-Reporting und die Kampagnenperformance auswirken.

Informationen zur Einrichtung der Deduplizierung findest du in der folgenden Dokumentation für Entwickler*innen:

Hier findest du ein Beispiel für die Protokollierung von selbstdefinierten Events. Übergib hierfür den Namen des Events als AppEvents.Name an das iOS-SDK:

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

Für App-Installations-Events gibt es bereits einen Deduplizierungsmechanismus, der sicherstellt, dass im letzten 90-Tage-Fenster nur eine Installation zugeordnet wird Wir behalten das erste Event und ignorieren die neueren Events unabhängig von ihrer Handlungs-Quelle. Die Deduplizierung für mit Installations-Events verwandten App-Events muss nicht zwingend implementiert werden.

d. Senden von Events

Tätige zum Senden neuer Events eine POST-Anfrage von folgendem Pfad an die Conversions API: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}. Wenn du in dieser Edge postest, erstellt Meta neue App-Server-Events. Mehr dazu findest du im folgenden Entwicklungsdokument.

Hier findest du eine Übersicht dazu, wie sich die Parameter in das Gesamtschema in der Payload einfügen:

**Problembehebung**

Mit dem Payload-Hilfstool kannst du Payload-Daten generieren:

Wähle gegebenenfalls die Handlungs-Quelle app.
Gib Informationen zu den Events ein, die an Meta gesendet werden.
Dadurch wird die Event-Payload generiert, die als Vorlage für deine Conversions API-Integration verwendet werden kann.

Verwende das Test-Events-Tool im Events Manager zum Testen.