Conversions API

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.

ParameterBeschreibung

event_time

Typ: int

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


store_data
Typ: JSON-Wörterbuch

Optional

Standortdaten zu Conversion-Event speichern.

Beispiel:

"store_data":
    {
        "store_page_id": 8576093908, // FBID
        "brand_page_id": 10236898932// FBID
    }

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


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



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.

Siehe auch

Artikel im Hilfebereich für Unternehmen