Facebook Pixel: Conversions API

Serverseitige Events über die Meta Conversions API im Facebook Pixel Plugin für Shopware 6.7: Voraussetzungen, Einrichtung, welche Bedingungen ein Event erfüllen muss, Deduplizierung, Message Queue und Fehlerverhalten.

English Version

Zurück zur Übersicht

Facebook Pixel: Conversions API

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Die Meta Conversions API (CAPI) sendet Events zusätzlich zum Browser-Pixel direkt vom Server an Meta. Die Events sind vom Browser unabhängig, Adblocker und Browser-Einschränkungen erreichen sie also nicht. Meta nennt die Kombination aus beidem Redundant Setup.

Datenschutz: Die Conversions API überträgt serverseitig auch die IP-Adresse und den User-Agent des Besuchers, und zwar nicht gehasht. Nur E-Mail und Telefonnummer werden gehasht. Details: Datenschutz.

Einrichtung

Im Meta Events Manager unter Einstellungen > Conversions API einen Access Token erzeugen
In der Plugin-Konfiguration Conversions API aktivieren einschalten und den Access Token eintragen
Bei Server-seitige Events die gewünschten Events wählen (Meta empfiehlt mindestens PageView und Purchase)
Optional einen Test Event Code eintragen und mit Verbindung testen die Zugangsdaten prüfen
Sicherstellen, dass der Message-Consumer läuft (siehe Installation)
Den Test Event Code für den Livebetrieb wieder leeren

Wann wird ein Event serverseitig gesendet?

Ein Event geht nur raus, wenn alle folgenden Bedingungen erfüllt sind:

Nr.	Bedingung
1	Tracking aktivieren ist an und die Pixel ID besteht nur aus Ziffern
2	Conversions API aktivieren ist an und ein Access Token ist eingetragen
3	Das Event steht in Server-seitige Events
4	Die Einwilligung liegt vor: bei aktivem Klaro enthält das Cookie `klaro` den Service mit `true`, sonst bei Cookie-Einwilligung erforderlich ein erkanntes Consent-Cookie (siehe Consent und Cookies)
5	Die Anfrage ist eine Web-Anfrage mit Request-Kontext

Die Schalter der Tracking-Optionen wirken zusätzlich: Ist zum Beispiel Bestellungen tracken aus, entsteht gar kein Purchase-Event, weder im Browser noch auf dem Server.

Ablauf

Der Subscriber der Seite erzeugt das Event und gibt es an den Browser-Code. Gleichzeitig meldet er es intern als „Event versendet“.
Der Listener prüft die Bedingungen oben und hasht E-Mail und Telefonnummer.
Er legt eine Nachricht in die Message Queue. Die Seite wird dadurch nicht verlangsamt.
Der Consumer verarbeitet die Nachricht und sendet sie per HTTPS an die Graph API von Meta (graph.facebook.com, Version v21.0, Endpunkt /{pixel-id}/events). Das Zeitlimit beträgt 5 Sekunden.

Ein fehlgeschlagener Versand wird nicht wiederholt. Schlägt die Anfrage fehl, schreibt das Plugin eine Warnung ins Log (Channel mmd_facebook_pixel), und das Event geht verloren.

Deduplizierung

Browser und Server verwenden pro Event dieselbe ID: im Browser als eventID, am Server als event_id. Meta erkennt dadurch, dass beide dasselbe Ereignis beschreiben, und zählt es einmal. Doppelte Einträge im Events Manager sind im Redundant Setup deshalb erwartetes Verhalten, solange sie dedupliziert werden.

Was wird gesendet?

Feld	Inhalt
`event_name`	Name des Events (zum Beispiel `Purchase`)
`event_id`	Event-ID, identisch zur `eventID` im Browser
`event_time`	Zeitpunkt, an dem die Nachricht erzeugt wurde (Unix-Zeit)
`event_source_url`	Vollständige URL der aufgerufenen Seite
`action_source`	immer `website`
`custom_data`	Dieselben Event-Daten wie im Browser, siehe Events und Daten. Das Feld entfällt, wenn ein Event keine Daten hat, also bei PageView.
`user_data`	Siehe Datenschutz

Ist ein Test Event Code eingetragen, wird er als test_event_code mitgesendet.