Facebook Pixel: Technische Details

Facebook Pixel Plugin für Sylius: Ablauf, Plugin-Struktur, Entity, Admin-Verdrahtung und Messenger-Routing der CAPI-Nachrichten.

English Version

Zurück zur Übersicht

Facebook Pixel: Technische Details

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

Ablauf

graph TD
    A["Twig Hook / Add-to-Cart-Event"] --> B["ChannelConfigurationResolver"]
    B --> C{"Event für Channel getrackt?"}
    C -->|"Nein"| D["Nichts rendern"]
    C -->|"Ja"| E["fbq-Skript rendern"]
    C -->|"Ja"| F["PixelEventDispatched"]
    F --> G["CapiEventListener"]
    G --> H{"CAPI ausgewählt und Einwilligung ok?"}
    H -->|"Nein"| I["Stop"]
    H -->|"Ja"| J["PiiHasher hasht E-Mail und Telefon"]
    J --> K["Messenger: SendCapiEventMessage"]
    K --> L["SendCapiEventHandler"]
    L --> M["ConversionsApiClient"]
    M --> N["Meta Conversions API"]

Beide Hälften eines Events, der gerenderte fbq()-Aufruf und das ausgelöste PixelEventDispatched, entstehen an derselben Aufrufstelle und teilen sich eine einmal erzeugte event_id (PixelEventIdGenerator). Bei AddToCart entsteht die serverseitige Kopie im Listener auf sylius.cart_item_post_add, der Browser-Aufruf wird über die Session an die nächste Seite übergeben.

Die Einwilligungsprüfung und das Hashing laufen synchron im Request, weil nur dort die Cookies und Kundendaten verfügbar sind. Jeder Fehler in dieser Kette wird geloggt und verschluckt, damit eine Störung beim Tracking nie die Seite oder die Warenkorb-Aktion zum Absturz bringt.

Plugin-Struktur

src/
├── Api/                Shop-API-Resource + Provider (nur lesende Settings)
├── Capi/               Conversions-API-Payload, Client, PII-Hasher, Server-Event-Kontext
├── Command/            SetupCommand (bin/console mmd:facebook-pixel:setup)
├── Consent/            CapiConsentPolicy + CapiConsentEvidenceProviderInterface, Klaro-Cookie-Reader
├── Customer/           Ermittelt die E-Mail des eingeloggten Kunden für das CAPI-Matching
├── Entity/             ChannelConfiguration (eine Zeile pro Sylius-Channel)
├── Event/              PixelEventDispatched
├── EventListener/      AddToCartListener, CapiEventListener, ProvisionKlaroServiceListener
├── Form/Type/          Admin-Formular (ChannelConfigurationFormType)
├── Klaro/              Laufzeit-Erkennung von Klaro, Consent-Gate, Katalog-Anlage
├── Menu/               Admin-Sidebar-Eintrag (Gruppe MMKreativ Plugins)
├── Messenger/          SendCapiEventMessage + zugehöriger Handler
├── Migrations/         Vier Doctrine-Migrationen (siehe Installation)
├── Model/              Enum FacebookPixelEvent, PendingAddToCartFlash
├── Renderer/           Baut das fbq()-Skript-Markup
├── Repository/         ChannelConfigurationRepository
├── Resolver/           ChannelConfigurationResolver (Channel zu Settings-Zeile)
├── Security/           CapiAccessTokenCipher (libsodium secretbox)
├── Service/            PixelEventIdGenerator
└── Twig/               FacebookPixelTwigExtension (die von den Hooks aufgerufenen Funktionen)

Entity

ChannelConfiguration (Tabelle mmd_sylius_facebook_pixel_channel_configuration), eine Zeile pro Channel (eindeutig auf channel_id):

Spalte	Typ	Hinweise
`channel_id`	int, unique FK	`ON DELETE CASCADE`
`enabled`	bool	Hauptschalter, Standard aus
`pixel_id`	string(32), nullable	Nur Ziffern, per Formular-Validierung geprüft
`track_page_view` ... `track_purchase`	bool	Je eine Spalte pro Browser-Event, Standard an
`track_gross_prices`	bool	Standard an
`use_klaro_consent`	bool, Standard true	Klaro-Gating-Kästchen
`capi_enabled`	bool	Standard aus
`capi_require_consent_evidence`	bool, Standard true	Fail-Closed-Einwilligungspflicht
`capi_access_token_ciphertext`	text, nullable	Verschlüsselt, nie im Klartext
`capi_test_event_code`	string(255), nullable
`capi_event_selection`	json	Liste der per CAPI gesendeten `FacebookPixelEvent`-Werte, Standard leer

Admin

Resource	Routen-Alias	Grid
Channel-Einstellungen	`mmd_sylius_facebook_pixel_plugin.channel_configuration`	`mmd_sylius_facebook_pixel_plugin_admin_channel_configuration` (Channel, Pixel-ID, Tracking aktiviert, Conversions API aktiviert)

Die Seite ist im Admin unter MMKreativ Plugins > Facebook Pixel erreichbar (Icon tabler:brand-meta) und liegt unter dem Pfad /<admin-pfad>/facebook-pixel-channel-configurations. Fehlt der Admin-Routen-Import, fehlt nur der Menüeintrag; die übrigen Admin-Seiten bleiben unberührt.

Messaging

SendCapiEventMessage wird an den main-Messenger-Transport geroutet, den Sylius selbst für asynchrone Aufgaben nutzt. Es ist kein eigener Transport nötig, aber ein laufender Worker (bin/console messenger:consume), sonst bleiben die Nachrichten liegen.

Die Nachricht trägt den Channel-Code, Eventname, Event-ID, Zeitstempel, Quell-URL, Event-Daten, IP-Adresse, User-Agent, die Cookie-Werte _fbc/_fbp sowie die bereits gehashte E-Mail und Telefonnummer. Klartext-E-Mail oder -Telefonnummer sind nicht enthalten, und es gibt keinen Snapshot der Einstellungen: Der Handler liest die aktuelle ChannelConfiguration und das Token erst bei der Zustellung, sodass eine zwischenzeitlich geänderte Einstellung (oder abgeschaltete CAPI) berücksichtigt wird.

Der Aufruf an Meta geht per HTTP-POST an die Graph API (https://graph.facebook.com, Version v21.0) mit 5 Sekunden Timeout. Als Erfolg zählt nur HTTP 200; alles andere wird geloggt, ohne Wiederholung.