Facebook Pixel: Storefront-Integration
Facebook Pixel Plugin für Sylius: Twig Hooks pro Event, Event-Deduplizierung, Klaro-Consent-Gating, AddToCart-Timing und Preiswerte.
Facebook Pixel: Storefront-Integration
Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net
Twig Hooks
Jedes Event wird über einen Twig Hook gerendert, nie über ein überschriebenes Core-Template:
| Hook | Template | Event |
|---|---|---|
sylius_shop.base#javascripts |
bootstrap.html.twig |
Das fbq()-Bootstrap-Skript samt PageView, einmal pro Seite. |
sylius_shop.product.show.content |
view_content.html.twig |
ViewContent auf der Produktdetailseite. |
sylius_shop.product.index.content.body.main.header |
view_category.html.twig |
ViewCategory auf einer Kategorie-Listenseite (Custom Event). |
sylius_shop.cart.index.content |
add_to_cart.html.twig |
Das von der echten Add-Aktion vorgemerkte AddToCart-Skript (siehe unten). |
sylius_shop.checkout.address.content |
initiate_checkout.html.twig |
InitiateCheckout im ersten Checkout-Schritt. |
sylius_shop.order.thank_you.content |
purchase.html.twig |
Purchase auf der Bestellbestätigungsseite. |
Ein Theme, das einen dieser Hook-Punkte überschreibt, sieht das Pixel-Skript weiterhin, solange es den Hook in seiner eigenen Template-Version weiter rendert. Das ist der übliche Sylius-Twig-Hooks-Vertrag.
Die Templates rufen die Twig-Funktionen mmd_facebook_pixel_bootstrap, mmd_facebook_pixel_view_content, mmd_facebook_pixel_view_category, mmd_facebook_pixel_initiate_checkout, mmd_facebook_pixel_purchase und mmd_facebook_pixel_pending_add_to_cart auf. Jede liefert nichts, wenn der Channel keine gültige Konfiguration hat oder das Event ausgeschaltet ist.
Gesendete Event-Daten
| Event | Inhalt (custom_data) |
|---|---|
PageView |
keine |
ViewContent |
content_ids (Variantencode der ersten aktiven Variante), content_name, content_type (product), currency, value (Variantenpreis des Channels; entfällt, wenn für den Channel kein Preis hinterlegt ist) |
ViewCategory |
content_name, content_category (Pfad der Kategorie, z. B. Kleidung > Shirts) |
AddToCart |
content_ids, content_name, content_type, value, currency, num_items (Position, die gerade hinzugefügt wurde) |
InitiateCheckout, Purchase |
content_ids (Variantencodes), content_type, value, currency, num_items, order_id (Bestellnummer) |
Der Browser-Aufruf trägt immer {eventID: '...'} als letztes Argument. Die Skripte sind XSS-sicher kodiert.
Event-Deduplizierung
Jedes Event teilt sich genau eine event_id zwischen dem fbq()-Aufruf im Browser und der passenden serverseitigen CAPI-Nachricht, falls eine gesendet wird. Das ist der Mechanismus, mit dem Meta die beiden Kopien zu einem Event zusammenfasst. Die ID wird einmal pro Aufruf erzeugt und für beide Hälften wiederverwendet.
PageView,ViewContent,ViewCategoryundAddToCartbekommen eine zufällige ID (32 Hex-Zeichen).InitiateCheckoutundPurchasebekommen eine stabile ID aus der Bestellung (initiate_checkout_...bzw.purchase_..., gefolgt von einem SHA-256-Hash der Bestell-ID bzw. Bestellnummer). Dadurch zählt Meta ein erneutes Laden der Seite nicht als zweiten Kauf.
AddToCart-Timing
Anders als eine Prüfung bei jedem Laden der Warenkorbseite reagiert AddToCart auf Syliuss eigenes Event sylius.cart_item_post_add, also auf die echte Add-Aktion, genau einmal pro Hinzufügen. Die serverseitige Kopie entsteht sofort an dieser Stelle.
Da die Add-Aktion keine vollständige Seite rendert, kann das Browser-Skript nicht direkt von dort ausgegeben werden: event_id und Produktdaten werden in der Session vorgemerkt (Flash-Bag) und beim nächsten vollständigen Seiten-Render über den Hook sylius_shop.cart.index.content ausgegeben, typischerweise auf der Warenkorbseite. Pro Add-Aktion wird ein Skript ausgegeben; die Vormerkung wird dabei verbraucht.
Prüfe den Ablauf vor dem Produktiveinsatz einmal im echten Browser: "In den Warenkorb" klicken und im Network-Tab oder mit der Meta-Pixel-Helper-Erweiterung kontrollieren, dass
AddToCartmit einereventIDerscheint.
Consent-Gating (Browser-Pixel)
Dieser Abschnitt betrifft nur den Browser-Pixel. Die Einwilligung für die serverseitige CAPI ist eine eigene, strengere Einstellung. Siehe Konfiguration und Erweiterbarkeit.
Ist Tracking-Skripte über Klaro-Einwilligung freischalten angehakt und mmd/sylius-klaro-consent-plugin installiert, wird jedes Pixel-Skript nach Klaros Konvention ausgegeben:
<script type="text/plain" data-type="application/javascript" data-name="facebook_pixel">
Der Browser führt es dann erst aus, wenn Klaro die Einwilligung für den Dienst facebook_pixel erteilt hat. Das Speichern der Channel-Einstellungen mit angehaktem Kästchen legt diesen Dienst im Klaro-Katalog an, falls er noch nicht existiert (Zweck marketing, Cookies _fbp, _fbc und fr, Titel und Beschreibung auf Deutsch und Englisch). Ein bestehender, auch von Hand bearbeiteter Eintrag wird nie überschrieben.
Wirksames Gating ist Kästchen UND installiertes Klaro. Das Kästchen ist im Admin deaktiviert, solange Klaro fehlt. Ohne Klaro (oder bei abgewähltem Kästchen) werden die Skripte als normale, ausführbare <script>-Tags ausgegeben. Ein Shop mit einem anderen Consent-Tool muss das Pixel-Skript dann selbst blockieren.
Preiswerte
Der value von ViewContent ist der im Channel hinterlegte Variantenpreis der Produktvariante, unverändert übernommen. Das Plugin rechnet dort keine Steuer um, daher wirkt Brutto-Preise tracken nicht auf ViewContent. Bei AddToCart, InitiateCheckout und Purchase stammen die Werte aus den Summen der Position bzw. der Bestellung; hier wählt die Einstellung zwischen Summe mit Steuer und Summe ohne Steuer (Bestellsumme abzüglich Steuerbetrag).
Bei ViewContent wird als Währung die Basiswährung des Channels angegeben, bei InitiateCheckout, Purchase und AddToCart die Währung des Warenkorbs bzw. der Bestellung.