Meta / Facebook Pixel Event Tracking ＆ Conversion API

Installationsanleitung, Dokumentation und FAQs zum Shopware Plugin

1. Installation und Basis-Aktivierung

  1. Lade die App in deiner Shopware Administration unter Erweiterungen / Apps hoch und installiere sie.
  2. Gehe in die Konfiguration der App.
  3. Füge deine benötigte Facebook Pixel ID in das entsprechende Feld ein.
  4. Aktiviere die App.

2. Einrichten des Conversion Access Tokens (für die Conversion API)

Um die Facebook Conversions API für zuverlässigeres, serverseitiges Tracking nutzen zu können, benötigst du einen Access Token.

  1. Generiere den Facebook Pixel Conversion Access Token. Die aktuellste und detaillierteste Anleitung zur Generierung des Tokens findest du direkt in der Facebook Developer Dokumentation: https://developers.facebook.com/docs/marketing-api/conversions-api/get-started/?locale=de_DE#use-your-own-app
  2. Kopiere den generierten Access Token und füge ihn in das Feld Conversion Access Token in der Plugin-Konfiguration ein.

3. Integration mit deinem externen Cookie Consent Manager (Expertenmodus)

Je nachdem, welchen externen Cookie Consent Manager (CCM) du verwendest, muss der Wert des **data-Attributs** korrekt konfiguriert werden, damit das Facebook Pixel erst nach Zustimmung geladen wird.

  • Wenn du das Feld leer lässt, verwenden wir die Standardwerte:
    • Für User Centrics: Der Standardwert ist „Facebook Pixel“.
    • Für Cookie Bot: Der Standardwert ist „marketing“.
  • Für eine manuelle Konfiguration (Expertenmodus): Folge der spezifischen Anleitung für deinen CCM, um den korrekten Wert zu ermitteln und trage diesen in das Expertenfeld ein.

4. Opt-out-Link für Facebook Pixel bereitstellen

Um deinen Nutzern die Möglichkeit zu geben, das Tracking durch das Facebook Pixel gezielt zu deaktivieren (Opt-out), unterstützt unser Plugin einen einfachen HTML-Code.

Binde folgenden HTML-Code auf einer beliebigen Seite deines Shops ein (z.B. in den Datenschutzhinweisen):

<a onclick="javascript:fbqOptout();" >Hier Facebook Pixel Tracking für diese Website abschalten</a>

Nach dem Klick auf diesen Link wird das Tracking für den Nutzer deaktiviert.

5. Eigenes Logfile für das Facebook-Pixel-Plugin

Wer die Einträge des Plugins in ein separates, täglich rotierendes Logfile schreiben lassen möchte, ergänzt in seiner Shopware-Installation die Datei config/packages/monolog.yaml (anlegen, falls nicht vorhanden) um folgenden Block:

monolog:
    channels: ["biloba_ad_facebook_pixel"]
    handlers:
        biloba_ad_facebook_pixel:
            type: rotating_file
            path: "%kernel.logs_dir%/biloba_ad_facebook_pixel_%kernel.environment%.log"
            level: debug
            channels: ["biloba_ad_facebook_pixel"]
            max_files: 14

Anschließend bin/console cache:clear ausführen. Die Einträge landen dann in var/log/biloba_ad_facebook_pixel_prod-JJJJ-MM-TT.log.

Mit level: debug werden sowohl Fehler als auch die Payloads aller erfolgreichen API-Aufrufe mitgeschrieben – unabhängig davon, ob synchron oder asynchron versendet wird. Die Plugin-Einstellung „Facebook Pixel Conversion API Logging aktivieren“ wird damit faktisch überflüssig und kann auf „aus“ bleiben.

Nur über die Plugin-Einstellung loggen (ohne eigenes Logfile)

Wer keinen eigenen Monolog-Handler anlegen möchte, kann alternativ den Plugin-Config-Schalter nutzen – mit zwei Einschränkungen:

  1. In den Plugin-Einstellungen „Conversion-API-Aufrufe asynchron über die Shopware Message Queue senden“ deaktivieren (der Toggle für das Logging greift nur im Sync-Pfad).
  2. „Facebook Pixel Conversion API Logging aktivieren“ einschalten.
  3. Im Shopware-Haupt-Logger das Level auf mindestens info setzen (siehe Abschnitt „Log-Level im Haupt-Log“).

Die Payloads landen dann im allgemeinen var/log/prod-*.log und müssen per grep gefiltert werden.

Einträge aus dem Haupt-Logfile filtern

Einträge aus dem gemeinsamen Shopware-Logfile:

grep -a "biloba_ad_facebook_pixel" var/log/prod-$(date +%F).log > fb-pixel.log

Log-Level im Haupt-Log

Damit im allgemeinen Shopware-Log neben Fehlern auch info– oder debug-Einträge sichtbar werden, in config/packages/prod/monolog.yaml den level des main-Handlers entsprechend senken (info für Payloads, debug für Erfolgs-Logs) und den Cache leeren. Beim Weg über das eigene Logfile (siehe oben) ist das nicht nötig.

FAQs

Ja, unser Plugin bietet die Möglichkeit, die Conversion API zu nutzen.

Dies kann bis zu 48 Stunden dauern (bitte checken, ob der Wert passt)

Die shopware.yaml, oder besser eine z-shopware.yaml im /config/packages Ordner (dort wo auch der Admin Worker ausgeschaltet wird) erweitern:

    messenger:
        routing_overwrite:
‘Biloba\AdFacebookPixel\Core\Messages\ConversionApiMessage’: low_priority

Dies verschiebt die Conversion Nachrichten der Facebook Pixel Erweiterung in die ”low_priority queue” der ”messenger_messages” Tabelle der Datenbank

Keine Lösung gefunden?

Beschreibe uns Dein Problem – wir schauen uns das an und melden uns schnellstmöglich.

support-Anfrage stellen