DataFirefly Server-Side voor Shopware: complete gids

Overzicht

DataFirefly Server-Side is de gratis Shopware-connector van de dienst DataFirefly Server-Side Tracking. Bij elke bevestigde bestelling bouwt de plugin een volledig aankoopevent op en stuurt dit van server naar server, ondertekend met HMAC-SHA256, naar de in de EU gehoste DataFirefly-dispatcher. De dienst neemt het event op, ontdubbelt het en verspreidt het naar uw bestemmingen: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API en Google Ads.

De plugin is bewust minimalistisch aan shopzijde: er worden geen inloggegevens van bestemmingen opgeslagen, er wordt geen script aan de storefront toegevoegd en er wordt geen tabel aangemaakt. Hij vangt op, bouwt op, ondertekent en verstuurt; de rest gebeurt aan de kant van de dienst.

Vereisten

• Shopware 6.5.x, 6.6.x of 6.7.x (zelfgehoste installatie, want Shopware Cloud accepteert geen serverplugins)
• PHP 8.1 of hoger, afhankelijk van uw Shopware-versie, met de curl-extensie
• Een actief abonnement op de dienst DataFirefly Server-Side Tracking om uw verbindingssleutel te krijgen

Installatie

Via ZIP-upload

1. Open in de Shopware-administration Extensies → Mijn extensies → Extensie uploaden en selecteer het ZIP-bestand van de plugin.
2. Klik op Installeren en daarna op Activeren.

Via de commandoregel

bin/console plugin:refresh
bin/console plugin:install --activate DatafireflyServerSide
bin/console cache:clear

Verbinding met de dienst

Uw verbindingssleutel verkrijgen

1. Log in op uw klantomgeving op server-side.datafirefly.com.
2. Open het onderdeel Uw shop verbinden.
3. Kopieer de verbindingssleutel op één regel, in het formaat dfss_…. Deze bevat uw tenant-identificatie, uw HMAC-ondertekeningsgeheim en het ingest-endpoint.

De sleutel in Shopware plakken

1. Open Extensies → Mijn extensies → DataFirefly Server-Side → Configuratie.
2. Plak de sleutel in het veld Verbindingssleutel.
3. Zet de schakelaar Tracking activeren aan en sla op.

Meer is niet nodig: vanaf de volgende bevestigde bestelling vertrekt het aankoopevent naar de dispatcher. Een ontbrekende of verkeerd opgemaakte sleutel is nooit een blokkerende fout; de plugin gaat er dan simpelweg van uit dat hij niet geconfigureerd is en verstuurt niets.

Configuratie

• Tracking activeren: hoofdschakelaar. Standaard uitgeschakeld.
• Verbindingssleutel: de sleutel dfss_… die u uit uw klantomgeving hebt gekopieerd.
• Marketingtoestemming vereisen: activeert de toestemmingsgate (standaard uitgeschakeld, zie hieronder).
• Naam van de toestemmingscookie: de cookie die door uw toestemmingstool (CMP) wordt geplaatst.
• Waarde van de toestemmingscookie (bevat): optioneel, het verwachte deel van de waarde in de cookie.

De configuratie wordt per sales channel beheerd: u kunt tracking op de ene shop wel en op de andere niet activeren, of per kanaal verschillende sleutels gebruiken.

Toestemmingsgate

Shopware plaatst niet standaard één enkele, server-side leesbare cookie voor marketingtoestemming. De plugin biedt daarom een generieke gate, standaard uitgeschakeld: als deze actief is, wordt het aankoopevent alleen verstuurd wanneer de ingestelde cookie in de aanvraag van de klant aanwezig is, en, als er een verwachte waarde is ingevuld, alleen wanneer de waarde van de cookie die bevat.

Met DataFirefly Cookie Consent

De aanbevolen combinatie op Shopware is onze plugin DataFirefly Cookie Consent (AVG-banner met native Google Consent Mode v2): activeer de gate en vul de naam in van de toestemmingscookie die de banner plaatst (vermeld in de bijbehorende documentatie). Weigering of afwezigheid van marketingtoestemming blokkeert de verzending aan serverzijde, vóór elke doorgifte.

Met een andere CMP

Vul de naam in van de cookie die uw CMP plaatst wanneer de bezoeker marketingcookies accepteert (bijvoorbeeld CookieConsent voor Cookiebot), en eventueel een deel van de waarde (bijvoorbeeld marketing:true). Als uw CMP geen server-side leesbare cookie plaatst, of als u de toestemming volledig stroomopwaarts beheert, laat u de gate uitgeschakeld.

Privacy-first gedrag

• Gate actief en cookienaam niet ingesteld → er vertrekt niets.
• Gate actief en cookie afwezig of leeg → er vertrekt niets.
• Gate actief en verwachte waarde ingesteld maar niet aanwezig in de waarde van de cookie → er vertrekt niets.
• Geen aanvraag aanwezig (CLI- of headless-stroom zonder HTTP-aanvraag) → er vertrekt niets.

De verbinding testen

De plugin levert een consolecommando dat een synthetische page_view naar de dispatcher stuurt, zonder de echte bestellingen aan te raken:

bin/console datafirefly:serverside:test

Beschikbare opties:

• --sales-channel-id=<id>: leest de configuratie van een specifiek sales channel (standaard: de globale configuratie).
• --source-url=<url>: neemt een sourceUrl op in het testevent.

Een HTTP-code 2xx bevestigt dat de verbindingssleutel, de handtekening en het endpoint correct zijn, ook als er aan de kant van de dienst nog geen bestemming is ingesteld.

Technische werking

Het purchase-event

De plugin abonneert zich op het event van een bevestigde bestelling in Shopware. Bij elke trigger bouwt hij een purchase-event met een idempotente identificatie op basis van de bestelling (order_<id>): als u ook browsertags gebruikt, past de dienst deduplicatie toe over client en server, zodat elke conversie maar één keer wordt geteld.

Verzonden gegevens

• Transactie: betaald bedrag, valuta, bestelnummer, producten, hoeveelheden, aantal artikelen.
• Matching: e-mail, klant-id, telefoon, voornaam, achternaam, plaats, postcode en land van het factuuradres.
• Browser-identificaties die op het moment van de bestelling worden vastgelegd: _fbp, _fbc, _ttp en de GA4 client id (cookie _ga).

De opbouw is defensief: elk optioneel veld wordt alleen toegevoegd als het aanwezig en geldig is (de dispatcher valideert streng: land op 2 tekens, valuta op 3, enzovoort). In headless-stromen waarin bepaalde associaties van de bestelling kunnen ontbreken, worden de betreffende velden simpelweg weggelaten, nooit verzonnen.

HMAC-handtekening

Elk event wordt ondertekend met HMAC-SHA256 met uw tenant-geheim: de ondertekende bytes zijn exact de verzonden bytes, met een tijdstempel dat binnen een venster van 300 seconden wordt gecontroleerd tegen replay. De doorgegeven headers zijn de tenant-identificatie, de tijdstempel en de handtekening. Uw inloggegevens voor Meta, GA4, TikTok, Pinterest en Google Ads blijven aan de kant van de dienst, nooit in de shop en nooit in de browser.

Fail-safe

Het hele subsysteem is zo ontworpen dat het de checkout nooit beïnvloedt: time-outs van 2 seconden (verbinding) en 4 seconden (totaal), alle fouten worden opgevangen en als waarschuwing geregistreerd in de Shopware-logs met de HTTP-code en het bestelnummer; er komt geen enkele exception tot in het besteltraject.

Probleemoplossing

• Er vertrekt geen enkel event: controleer of de schakelaar geactiveerd is voor het juiste sales channel, of de sleutel begint met dfss_ zonder spatie of regeleinde, en of de toestemmingsgate niet actief is zonder ingestelde cookie.
• Het testcommando mislukt: een code 0 met een curl-melding wijst op een uitgaand netwerkprobleem (firewall); een code 401/403 wijst op een ongeldige of opnieuw gegenereerde sleutel, kopieer hem dan opnieuw uit uw klantomgeving.
• Events gemarkeerd als niet afgeleverd in de logs: de HTTP-code en het bestelnummer worden in de Shopware-logs geregistreerd (kanaal warning). Een 4xx-code wijst op een payload die door de strenge validatie van de dispatcher is afgewezen; raadpleeg de Event Inspector in uw klantomgeving voor de details.
• Dubbele conversies op Meta of GA4: controleer of uw browsertags dezelfde event-identificatie (order_<id>) versturen om van de deduplicatie te profiteren.

Changelog

• 1.0.0 (01-07-2026): eerste versie met idempotent server-side purchase-event, HMAC-SHA256-handtekening met antireplay-venster, verbindingssleutel op één regel, opt-in toestemmingsgate via CMP-cookie, configuratie per sales channel, consolecommando voor tests en fail-safe ontwerp.