3: Entwicklungsimplementierung

Auf dieser Seite geht es um die manuelle Integration und es werden folgende Themen behandelt:

• Erstellung der Payload für die CRM-Integration
• Generieren eines Zugriffsschlüssels und Vorbereiten eines API-Aufrufs
• Senden einer Test-Payload
• Senden von Produktionsdaten

Dieser Abschnitt ist nur dann für dich relevant, wenn du die Integration manuell mithilfe von Entwicklungsressourcen durchführen möchtest. Wenn du diese Integration stattdessen mit einem Partner durchführen möchtest, befolge bitte die entsprechenden Partneranweisungen für die Integration. Du kannst zum Abschnitt 4: Überprüfen deiner Daten springen, wenn die Partnerintegration abgeschlossen ist.

Du benötigst Admin-Zugriff auf Business Manager, um diese Integrationsschritte durchzuführen. Wenn du als Entwickler*in eingeladen wurdest, kannst du über die E-Mail Zugriff erhalten, die dir zugesendet wurde. Ansonsten kannst du Zugriff bei einem Business Manager-Admin beantragen.

Schritt 1: Erstellen einer Payload

Dieser Schritt definiert die Payload-Anforderungen für die Conversion-Leads-Integration und bietet Empfehlungen, wie du diese von deinem Server senden kannst.

1. Öffne auf dem Tab Einstellungen deines CRM-Pixels das CRM-Integrationshandbuch, um zu beginnen.


2. Im Entwicklungsleitfaden zu Conversion API findest du Informationen zur Funktionsweise der Conversion API.


3. Wir empfehlen, zum Erstellen deiner Payloads das Payload-Hilfstool zu verwenden. Das Payload-Hilfstool formatiert deine Payload und prüft auf Fehler. Sobald alle Payload-Fehler behoben sind, klicke auf den Button Get Code (Code erhalten) im Payload-Hilfstool, um eine Code-Vorlage für deine Programmiersprache zu generieren.


4. Hier ist die Liste der erforderlichen Parameter. Eine umfangreiche Beschreibung der jeweiligen Parameter findest du im Leitfaden zur Payload-Spezifikation für die Conversion Leads-Integration. Diese Payload-Spezifikation sollte nur für Events zur Optimierung von Conversions verwendet werden. Dies bedeutet, dass Events nur für Meta-Lead-Anzeigen gelten und eine gültige Lead-ID haben sollten. Verwende diese Payload-Spezifikation nicht für andere Event-Typen, wie z. B. Website-Leads.
   
   Parameter

   Name	Beschreibung
   event_name String	Freiformfeld zur Erfassung der Lead-Phasen, die du in deinem CRM verwendest. Der event_name-Parameter sollte einen Lead angeben, der den Sales-Funnel in deinem CRM durchläuft. Stelle sicher, dass alle Phasen gesendet werden, wenn sie aktualisiert werden, einschließlich des Raw-Leads.
   event_time Integer	Ein Unix-Zeitstempel in Sekunden, der angibt, wann das Update-Event für die Lead-Phase von deinem CRM aktualisiert wurde. Der Zeitstempel muss nach der Lead-Generierungszeit liegen, andernfalls wird das Event ignoriert.
   action_source String	Wert:system_generated (Indem du die Conversions API verwendest, versicherst du, dass der Parameter action_source nach bestem Wissen und Gewissen richtig ist.)
   lead_id Integer	Die 15 oder 16 Ziffern leadgen_id aus deinen heruntergeladenen Leads.
   lead_event_source String	Der Name des CRM, aus dem die Events stammen.
   event_source String	Wert:crm

   
   
   Beispiel
   Eine Beispiel-Payload könnte wie folgt aussehen. Hinweis: Du musst eine gültige lead_id verwenden, anderenfalls lehnt das System dein Event ab.

   {
       "data": [
           {
               "event_name": "initial_lead",
               "event_time": 1629424350,
               "action_source": "system_generated",
               "user_data": {
                   "lead_id": 525645896321548
               },
               "custom_data": {
                   "event_source": "crm",
                   "lead_event_source": "salesforce"
               }
           }
       ]
   }
   
   



5. Wenn Events die Payload-Spezifikation nicht erfüllen oder keiner Meta-Lead-Anzeige entsprechen, werden sie nicht für die Integration anerkannt und werden nicht für das Trainingsmodell verwendet.
   So würde die Web-Payload von der Conversions API z. B. akzeptiert und in Events Manager angezeigt werden, aber sie wird nicht für diese Integration anerkannt. Außerdem musst du eine gültige lead_id verwenden. Ansonsten lehnt das System dein Event ab.
   Nur die Conversion-Leads-Payload wird für die Integration anerkannt und für das Training verwendet.

Schritt 2: Erstellen eines Zugriffsschlüssels und eines API-Aufrufs

Sobald du konfiguriert hast, was du senden möchtest, besteht der nächste Schritt darin, zu konfigurieren, wohin du die Daten senden möchtest.

Dieser Schritt hilft dir dabei, einen Zugriffsschlüssel für dein Meta-Pixel zu generieren, das dann verwendet wird, um eine Verbindung zwischen deinem Server und der Conversions API herzustellen.

1. Über das Einstellungen-Tab in deinem CRM-Pixel kannst du zum CRM-Integrationsleitfaden zurückkehren.


2. Scrollen Sie nach unten zum Abschnitt Create Endpoint (Endpunkt erstellen) und klicke auf den Button Generate Access Token (Zugriffsschlüssel generieren). Der Zugriffsschlüssel wird zum Erstellen deines API-Aufrufs verwendet.
   Du kannst einen neuen Zugriffsschlüssel generieren, indem du zum Integrationsleitfaden zurückkehrst oder im Einstellungen-Tab in Events Manager. Navigiere zum Abschnitt Conversions API und klicke auf den Link Generate access token (Zugriffsschlüssel generieren).


3. Der Rest dieser Anleitung variiert je nachdem, ob du das SDK von Meta verwendest. Es wird empfohlen, das Meta Business SDK zu verwenden, da es bessere Fehler- und Diagnosemeldungen bereitstellt. Du benötigst deine Pixel-ID und deinen Zugriffsschlüssel, um den API-Aufruf über das Meta Business SDK zu tätigen. Durch Klicken auf Copy access token (Zugriffsschlüssel kopieren) im CRM-Integrationsleitfaden kannst du den Zugriffsschlüssel abrufen und speichern. Beispiele für SDK-API-Aufrufe findest du im Conversion API Developers Guide oder der Get Code-Funktion im Meta-Payload-Hilfstool.


4. Dies ist das Endpunktformat, um eine POST-Anfrage an die Conversions API ohne SDK zu senden. Durch Klicken auf Copy endpoint (Endpunkt kopieren) im CRM-Integrationsleitfaden kannst du den gesamten Endpunkt abrufen und speichern.

   https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN

   • API_VERSION: Die aktuelle Marketing-API-Version
   • PIXEL_ID: Die Pixel-ID kann für jedes Pixel aus dem Events Manager abgerufen werden
   • ACCESS_TOKEN: Der oben generierte Zugriffsschlüssel
5. Die Termine für Marketing API-Releases und entsprechende Ablaufdaten findest du in der Dokumentation zur API-Version. Stelle sicher, dass du die API-Version oder das Meta Business SDK in deinem Code vor dem Ablaufdatum der Marketing API aktualisierst. Verwendest du eine veraltete Version in deinem Code, kann dies zu Fehlern führen und deine Events werden vom System möglicherweise abgelehnt.

Schritt 3: Testen einer Payload (optional)

An dieser Stelle solltest du einen Test-Payload an dein Pixel senden, bevor du den Code auf deinem Server implementierst. Du kannst dazu das Tab Test Events (Events testen) in Events Manager verwenden.

1. Klicke im Abschnitt Test Server Events (Server-Events testen) auf den Graph API Explorer-Link. Mit diesem eindeutigen Link werden einige Informationen von deinem Pixel vorausgefüllt. (Du kannst den Graph API Explorer auch direkt aufrufen.) Beachte den Wert test_event_code, der sich im Laufe der Zeit ändern kann.


2. Führe die folgenden Aufgaben im Graph API Explorer-Tool aus:
   1. Stelle sicher, dass du im POST-Modus bist.
   2. Stelle sicher, dass deine API-Version und Pixel-ID korrekt sind.
   3. Wechsle zur JSON-Ansicht.
   4. Gib deine Payload ein. Diese kann manuell erstellt werden oder mit dem Payload-Hilfstool generiert werden. Achte darauf, den test_event_code-Parameter aus dem vorherigen Schritt und eine gültige lead_id einzuschließen.
3. Gib deinen Pixel-Zugriffsschlüssel ein und klicke auf den Submit-Button (Senden).


4. Wenn deine Payload keine Syntax- oder API-Fehler enthält, solltest du eine Erfolgsnachricht mit einer fbtrace_id erhalten.


5. Das Test-Event sollte nach einer kurzen Zeit unter dem Test-Events-Tab in Events Manager angezeigt werden.

Schritt 4: Senden von Produktionsdaten

Die Produktionsdaten sollten im selben Format wie die Payload sein, die in Schritt 3 generiert wurde, nur kommen die Daten direkt von deinem Server. Dieser Schritt unterscheidet sich je nach Integration, daher werden hier Richtlinien statt einer konkreten Anleitung bereitgestellt.

1. Sende die lead_id anstatt PII für den Abgleich.


2. Stelle sicher, dass du alle Lead-Phasen sendest, wenn sie aktualisiert werden, einschließlich des Raw-Lead-Events, die alle Leads darstellt, die auf Meta generiert und in dein CRM heruntergeladen wurden. Es folgt ein Beispiel-Funnel. Die Event-Namen und -Phasen werden von Werbetreibenden definiert. Daher müssen sie nicht diesem Beispiel entsprechen.
   
   
   
   Wenn deine Kampagnen 100 Leads generieren, würden wir erwarten, dass 100 „Raw Lead“-Events hochgeladen werden, um die erste Lead-Phase darzustellen. Anhand der Übermittlung der ersten Lead-Phase wird das System darüber informiert, dass der Lead empfangen und verarbeitet wurde. Während die Leads den Sales-Funnel durchlaufen, würden wir erwarten, dass 70 „Marketing Qualified Lead“-, 30 „Sales Opportunity“- und 15 „Converted“-Phasen hochgeladen werden.
   
   Zur Erinnerung: Aus den Kampagnen werden 100 Leads generiert, aber in diesem Beispielszenario würden wir erwarten, dass 215 Events hochgeladen werden.


3. Erstelle eine Funktion, die Updates aus der API oder Datenbank deines CRM-Systems abruft, wenn der Status des Leads aktualisiert wird. Sende dann deine Payload mithilfe einer selbstdefinierten Funktion oder des Business-SDK von Meta an die Conversions API von Meta. Welche Integration für dich am besten geeignet ist, hängt von deiner CRM- und Datenbank-Konfiguration ab.
   
   Variablen sind empfehlenswert für:
   • lead_id
   • event_name
   • event_time
   Eine Payload, die explizit die Parameterwerte angibt, kann z. B. so aussehen:

   {
     "event_name": "initial_lead",
     "event_time": 1628294742,
     "user_data": {
       "lead_id": 1234567890123456
     },
     "action_source": "system_generated",
     "custom_data:" {
       "lead_event_source": "Salesforce",
       "event_source": "crm"
     }
   }
   

   Eine Payload, der Werte aus der Datenbank mit Variablen übergibt, kann wie folgt aussehen:

   {
     "event_name": lead_stage // "initial_lead"
     "event_time": unix_time // 1628294742
     "user_data": {
       "lead_id": fb_lead_id // 1234567890123456
     },
     "action_source": "system_generated",
     "custom_data:" {
       "lead_event_source": "Salesforce",
       "event_source": "crm"
     }
   }
   



4. Lade Daten mindestens einmal pro Tag hoch. Idealerweise sollten die Aufrufe an dein CRM in Echtzeit stattfinden, aber du kannst auch stündliche oder tägliche Batching-Methoden verwenden, wenn eine Echtzeit-Integration nicht möglich ist.
   Wenn du die Batching-Methoden wählst, stelle sicher, dass du den Änderungsverlauf des Lead-Status erfasst, anstatt nur einen Snapshot des Leads zur Zeit des Batchings. Wenn beispielsweise der Status eines Leads zwischen den Batches dreimal aktualisiert wird, würden wir drei Events für diesen Lead erwarten und nicht nur die letzte Aktualisierung.
   Hinweis: Jeder Batch kann bis zu 1.000 Events enthalten. Bei einem Fehler im Batch wird der gesamte Batch verworfen. Wir empfehlen daher dringend, kleinere Batches zu verwenden und eine Logik für Wiederholungsversuche hinzuzufügen.


5. Optional Wir empfehlen, Fehlernachrichten aus dem CAPI-Aufruf zu protokollieren und Alarme zu erstellen, wenn es Probleme gibt. Fehlerbehandlung für diese Fehler wäre auch eine gute Idee.


6. Du kannst deine Daten für bis zu sieben Tage in der Vergangenheit auffüllen. Der Zeitunterschied wird zwischen event_time und upload_time berechnet. Durch Backfilling einiger Daten kann der Trainingsprozess beschleunigt werden.

   WARNUNG: Vom Backfilling von Daten von mehr als sieben Tagen durch Modifizieren von event_time-Werten wird abgeraten. Die Model basiert auf einem genauen Zeitstempel, um eine Optimierung vorzunehmen. Das kann dazu führen, dass alle aufgefüllten Daten verworfen werden.

7. Stelle sicher, dass deine event_time-Werte nach dem Zeitstempel für die Lead-Generierung liegen, andernfalls können deine Events verworfen werden.


8. Wenn deine Integration Events zu Meta hochlädt, solltest innerhalb einer Stunde Events für dein Pixel im Events Manager sehen. Verwende bitte eine gültige lead_id in deinen Payloads, damit Events angezeigt werden. Öffne jedes Events, das für die Conversion-Leads-CRM-Integration gesendet wurde, in Events Manager und überprüfe, ob die selbstdefinierten Parameter lead_event_source und event_source ausgefüllt sind. Wenn das Event diese Parameter nicht enthält, wird es nicht als Conversion-Leads-Event registriert.
   
9. Das System prüft, ob deine Events gültige Conversion-Leads-Events ist. Nach einem Tag wird neben dem Schritt Send a CRM event (CRM-Event senden) der Integration ein grüner Haken angezeigt, wenn ein gültiges Event erkannt wird.