Senden von Offline-Events über die Conversions API

Die Conversions API ist Metas empfohlene Integrationsmethode für die Übermittlung von Offline-Events und Events in physischen Geschäften an Meta für die Verwendung für Anzeigenmessung, Attribution und Anzeigen-Targeting. Auf dieser Seite wird beschrieben, wie Offline-Events über eine Conversions API-Direktintegration oder -Partnerintegration gesendet werden können.

Voraussetzungen

Datensatz

Über die Conversions API gesendete Offline-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 an https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container durchführen, um festzustellen, ob der Datensatz des Werbetreibenden konsolidiert und somit zur Weitergabe von App-Events über die Conversions API autorisiert ist.

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

1. Einrichten von Parametern für Offline-Events

Werbetreibende können die hier erwähnte Einrichtung verwenden und die aktuelle Auswahl von Parametern verwenden, die über die Conversions API gesendet werden können. Um Offline- und Store-Events zu senden, können folgende Felder im Payload geteilt werden:

Werbetreibende müssen bei allen Offline- und Store-Events action_source als physical_store senden. Beachte, dass dieser Parameter für alle Server-Event-Typen erforderlich ist. Indem du die Conversions API verwendest, stimmst du zu, dass der Parameter action_source nach deinem bestem Wissen und Gewissen korrekt ist.
Alle erforderlichen -Server-Event-Felder für die Conversions API müssen beibehalten werden.
Kund*innen-Informationsparameter (unten findest du eine geeignete Liste von Parametern für Offline- und Store-Events).
Selbstdefinierte Datenparameter (unten findest du eine geeignete Liste von Parametern für Offline- und Store-Events).
Optionaler Parameter: Der upload_tag-Parameter wird weiterhin für Offline-Event-Uploads für Werbetreibende unterstützt, die die Legacy-API für Offline-Events verwenden.

Parameter für Kund*innen-Informationen

Die folgende Liste enthält Parameter für Kund*innen-Informationen, die üblicherweise für Offline- und Store-Events verwendet werden:

Parameternamen	Parameter	Hashing erforderlich
E-Mail-Adresse(n)	`email`	JA
Telefonnummer(n)	`phone`	JA
Geschlecht	`gen`	JA
Geburtsdatum	`db`	JA
Nachname	`ln`	JA
Vorname	`fn`	JA
Ort	`ct`	JA
US-Bundesstaaten	`st`	JA
Postleitzahlen	`zip`	JA
Land	`country`	JA
Apple Advertising Identifier	`madid`	JA
Android Advertising ID	`madid`	JA
Nutzer-ID von Drittanbietern	`external_id`	Dringend empfohlen
Die Lead-ID aus Lead Ads	`lead_id`	NICHT hashen

Selbstdefinierte Datenparameter

Der folgende Abschnitt enthält häufig verwendete selbstdefinierte Parameter, die von Offline- und Store-Events verwendet werden. Weitere selbstdefinierte Datenfelder findest du in der vollständigen Liste der Felder, die wir für die Conversions API akzeptieren unter folgendem Link.

Parameter Beschreibung

Parameter	Beschreibung
`event_time` Typ: Ganzzahl	Erforderlich Der UNIX-Zeitstempel für das Conversion-Event. Beispiel: `'1456870055'`
`event_name` Typ: String	Erforderlich Event-Typ. Beispiel: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`currency` Typ: String	Erforderlich ISO-Währungscode für dieses Conversion-Event mit drei Buchstaben. Für `Purchase`-Events erforderlich. Beispiel: `USD`
`value` Typ: Double	Erforderlich Wert des Conversion-Events. Für `Purchase`-Events erforderlich. Beispiel: `16.00`
`content_type` Typ: String	Optional Alle gültigen Advantage+ Catalog Ads`content_type`. Beispiel: `product`
`contents` Typ: JSON-Array	Optional. Erforderlich, wenn du deine Werbeanzeigen in deinen Katalog integrierst. Erforderlich: `id`, `quantity` Empfohlen: `price`, `brand`, `category` Erforderlich: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` Empfohlen: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` Typ: JSON-Wörterbuch	Optional. Informationen zu diesem Conversion-Event. Beispiel: `{category: 'ICECREAM'}`
`order_id` Typ: String	Optional. Eindeutige ID für jede Transaktion oder Bestellung in einer Offline-Event-Gruppe. Das kann für den Einzelhandel beispielsweise eine Quittungs-ID sein. Beispiel: `ATN10001`, `123456`
`item_number` Typ: String	Optional. Eindeutige ID zur Unterscheidung von Events innerhalb derselben Bestellung oder Transaktion. Beispiel: `1`, `a`

event_time

Typ: Ganzzahl

Erforderlich

Der UNIX-Zeitstempel für das Conversion-Event.

Beispiel:
'1456870055'

event_name
Typ: String

Erforderlich

Event-Typ.

Beispiel:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

currency
Typ: String

Erforderlich

ISO-Währungscode für dieses Conversion-Event mit drei Buchstaben. Für Purchase-Events erforderlich.

Beispiel:
USD

value
Typ: Double

Erforderlich

Wert des Conversion-Events. Für Purchase-Events erforderlich.

Beispiel:
16.00

content_type Typ: String

Optional

Alle gültigen Advantage+ Catalog Adscontent_type.

Beispiel:
product

contents

Typ: JSON-Array

Optional. Erforderlich, wenn du deine Werbeanzeigen in deinen Katalog integrierst.

Erforderlich: id, quantity

2. Senden von Events

Führe zum Senden neuer Events eine POST-Anfrage von folgendem Pfad an die Conversions API durch: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}.

Wenn du in dieser Edge postest, erstellt Meta neue Offline- und Store-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:

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

Wir empfehlen, Daten in Echtzeit oder mindestens täglich hochzuladen, um optimale Optimierungsergebnisse zu erzielen, damit Offline-Daten effektiv mit der Leistung von Anzeigen verglichen werden können, die du schaltest.

event_time kann bis zu 7 Tage vor dem Zeitpunkt liegen, zu dem du ein Event an Meta gesendet hast. Liegt eine event_time in data weiter als 7 Tage zurück, geben wir einen Fehler für die gesamte Anfrage zurück und verarbeiten keine Events. Bei Offline-Events und Events in physischen Geschäften mit physical_store als action_source solltest du Transaktionen innerhalb von 62 Tagen nach der Konversion hochladen.

Die Daten, die du hochlädst, werden in Echtzeit verarbeitet. Daher kannst du die Ergebnisse normalerweise direkt nach dem Hinzufügen der Daten sehen. Informationen zu Best Practices für Offline-Event-Daten findest du in diesem Dokument im Hilfebereich.

3. Einrichten von Deduplizierung

Anders als bei einer Deduplizierung, die für Conversions API- und Meta Pixel-Events eingerichtet ist, können Offline-Events nur mit anderen Offline-Events dedupliziert werden. Wir unterstützen zwei Methoden der Deduplizierung: basierend auf order_id oder basierend auf user. Die Deduplikation verwendet die Kombination von Feldern: dataset_id, event_time, event_name, item_number und das Schlüsselfeld basierend auf der Methode in der Payload des jeweiligen Events.

Die standardmäßige Deduplizierung verwendet order_id in Verbindung mit den oben genannten Feldern. Wenn order_id nicht im Payload vorhanden ist, wird die auf user basierte Deduplizierungslogik verwendet.

Wenn z. B. zwei Bestellungen mit identischen event_time- und event_name-Werten und derselben order_id oder demselben Satz von Kund*innen-Informationsparametern ohne order_id vorhanden sind, betrachten wir sie als doppelte Events und verwenden das erste Event. Die auf user basierte Deduplizierungsmethode funktioniert nur mit denselben Kund*innen-Informationsparameter-Feldern in den beiden Payloads.

Der maximale Deduplizierungszeitraum beträgt sieben Tage.

4. Fehlerbehandlung von Events

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

Wähle die Handlungs-Quelle physical_store, wenn anwendbar. Indem du die Conversions API verwendest, stimmst du zu, dass der Parameter action_source nach deinem bestem Wissen und Gewissen korrekt ist.
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. Bitte beachte, dass das Test-Events-Tool nur Web- und App-Events unterstützt.

Senden von Offline-Events über die Conversions API

Voraussetzungen

Datensatz

Berechtigungen

Konfiguration

1. Einrichten von Parametern für Offline-Events

Parameter für Kund*innen-Informationen

Selbstdefinierte Datenparameter

2. Senden von Events

3. Einrichten von Deduplizierung

4. Fehlerbehandlung von Events

Siehe auch

Artikel im Hilfebereich für Unternehmen