Facebook Pixel: Technische Details

Facebook Pixel Plugin für Shopware 6.7: Ablauf von Seitenaufruf bis Conversions API, Plugin-Struktur, Subscriber und Listener, Template-Block, Admin-Route des Verbindungstests und Plugin-Lebenszyklus.

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["Storefront-Seite wird geladen"] --> B["Subscriber prüft Konfiguration"]
    B -->|"Tracking aus oder Pixel ID ungültig"| C["nichts passiert"]
    B -->|"gültig"| D["EventDataExtractor erzeugt Event mit eventID"]
    D --> E["PixelEventDispatched"]
    D --> F["PixelJsRenderer erzeugt fbq-Aufruf"]
    E --> G["CapiEventListener"]
    G -->|"CAPI aus, Event nicht gewählt oder kein Consent"| H["verworfen"]
    G -->|"alle Bedingungen erfüllt"| I["SendCapiEventMessage in Queue"]
    I --> J["SendCapiEventHandler"]
    J --> K["ConversionsApiClient: graph.facebook.com"]
    F --> L["Template base.html.twig"]
    L -->|"Consent fehlt (Cookie-Prüfung)"| M["kein Skript"]
    L -->|"Consent da oder Klaro"| N["Skript im Browser"]

Plugin-Struktur

src/
├── MmdFacebookPixel.php         # Plugin-Klasse: Aktivierung, Deinstallation
├── Capi/                        # CAPI-Client, Verbindungstest, PiiHasher, Server-Kontext
├── Configuration/               # FacebookPixelConfig und Factory (liest die Systemkonfiguration)
├── Controller/Admin/            # TestConnectionController
├── Event/                       # PixelEvent und die sechs Event-Klassen, PixelEventDispatched
├── MessageQueue/                # SendCapiEventMessage und Handler
├── Migration/                   # Klaro-Service anlegen
├── Renderer/                    # PixelJsRenderer (erzeugt die fbq-Aufrufe)
├── Service/                     # ConsentChecker, EventDataExtractor, PixelCodeRenderer, KlaroServiceInstaller
├── Struct/                      # FacebookPixelStruct (Seiten-Extension fbPixelEvent)
├── Subscriber/                  # Seiten-Subscriber und CapiEventListener
└── Resources/                   # config.xml, Routen, Services, Snippets, Template, Admin-Komponente

Subscriber und Listener

Klasse	Hört auf	Aufgabe
`StorefrontRenderSubscriber`	`StorefrontRenderEvent`	Gibt Basiscode und PageView an das Template, meldet PageView für die CAPI
`ProductPageSubscriber`	`ProductPageLoadedEvent`	ViewContent
`CategoryPageSubscriber`	`NavigationPageLoadedEvent`	ViewCategory (lädt die Kategorie über `navigationId`)
`CheckoutSubscriber`	`CheckoutCartPageLoadedEvent`, `CheckoutConfirmPageLoadedEvent`	AddToCart (Warenkorbseite), InitiateCheckout (Bestätigungsseite)
`OrderCompletedSubscriber`	`CheckoutFinishPageLoadedEvent`	Purchase
`CapiEventListener`	`PixelEventDispatched`	Prüft die CAPI-Bedingungen, hasht E-Mail und Telefon, legt die Nachricht in die Queue

Die Seiten-Subscriber hängen das Tracking-Skript als Page-Extension fbPixelEvent an die Seite. Das Template storefront/base.html.twig erweitert @Storefront/storefront/base.html.twig und gibt im Block base_body_script Basiscode, PageView und das Event-Skript aus.

Erweiterungspunkte

PixelEventDispatched ist ein normales Symfony-Event. Wer es mit einem PixelEvent und einem ServerEventContext auslöst, schickt ein Event durch dieselben CAPI-Bedingungen wie die eingebauten.
PixelEventRendererInterface und ConversionsApiClientInterface sind als Interfaces registriert. Dahinter liegen PixelJsRenderer und ConversionsApiClient.

Die Klassen sind final. Eigene Events erstellst du daher durch eine eigene Ableitung von PixelEvent, nicht durch Erweitern der vorhandenen.

Admin-Route des Verbindungstests

Eigenschaft	Wert
Methode und Pfad	`POST /api/_action/mmd-facebook-pixel/test-connection`
Route-Name	`api.action.mmd_facebook_pixel.test_connection`
Berechtigung	`system_config:read`
Body (JSON)	`pixelId`, `accessToken`, optional `testEventCode`
Antwort (JSON)	`success`, `httpStatus`, `messageKey`, `metaErrorMessage`, `metaErrorCode`

messageKey ist einer der Werte success, missingPixelId, missingToken, invalidPixelId, metaError, networkError. Die Texte dazu stehen in den Admin-Snippets, siehe Konfiguration.

Plugin-Lebenszyklus

Zeitpunkt	Aktion
Installation/Update (Migration)	Legt den Klaro-Service `facebook-pixel` an, falls MmdKlaroConsent installiert ist
Aktivierung	Legt den Klaro-Service an, falls er noch fehlt und die Klaro-Tabelle existiert
Deinstallation ohne „Daten behalten“	Entfernt den Klaro-Service samt Übersetzungen und alle Einträge `MmdFacebookPixel.config.*` aus `system_config`

Weitere technische Eigenschaften

Die Pixel ID wird als JSON mit Escaping von <, >, & und Anführungszeichen ausgegeben, und sie muss nur aus Ziffern bestehen.
Die Konfiguration wird pro Sales Channel aus der Systemkonfiguration gelesen. Schalter, die in der Konfiguration nie gespeichert wurden, gelten als „An“ (Tracking-Optionen) beziehungsweise „Aus“ (Hauptschalter, Consent, Conversions API).
Nachrichten für die CAPI implementieren AsyncMessageInterface und laufen deshalb über den asynchronen Transport.
Fehler beim Versand werden protokolliert und nie als Ausnahme weitergegeben.