DataFirefly Server-Side: volledige gids

Overzicht

DataFirefly Server-Side is de gratis PrestaShop-connector van de dienst DataFirefly Server-Side Tracking. Bij elke bevestigde bestelling bouwt de module een volledige aankoopgebeurtenis op en stuurt die van server naar server, HMAC-SHA256-ondertekend, naar de DataFirefly-dispatcher, gehost in de EU (Duitsland). De dienst verspreidt de gebeurtenis daarna naar uw geconfigureerde bestemmingen: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API en Google Ads.

De rolverdeling is simpel: de module vangt op en ondertekent, de dienst ontvangt, dedupliceert en verspreidt. De module is gratis; de verspreiding vereist een abonnement op de dienst (Starter vanaf € 39/maand).

Vereisten

• PrestaShop 1.7.6 of hoger, 8.x of 9.x
• PHP 7.4 of hoger, met de cURL-extensie (aanwezig op vrijwel alle hostings)
• Een actief DataFirefly Server-Side Tracking-account; abonneer u op server-side.datafirefly.com
• Aanbevolen: onze module DataFirefly Cookie Manager (tarteaucitron-banner met Google Consent Mode v2) voor de native toestemmingsgate

Installatie

1. Download de ZIP van de module vanuit uw DataFirefly-account.
2. Open in de PrestaShop-backoffice Modules > Modulebeheer > Een module installeren en upload het bestand datafirefly_serverside.zip.
3. Klik op Installeren. De module registreert zich op de hook voor de orderbevestiging; er is geen override of themawijziging nodig.

Bij de installatie is de tracking uitgeschakeld en is de toestemmingsvereiste ingeschakeld: er vertrekt niets zolang u de module niet hebt geconfigureerd en geactiveerd.

Uw inloggegevens ophalen

1. Log in op uw DataFirefly-klantomgeving (of abonneer u als dat nog niet is gebeurd).
2. Open de sectie Uw winkel verbinden van uw site.
3. Kopieer de drie getoonde waarden: het Tenant ID (in het formaat shop_uwwinkel_xxxx), het HMAC-secret (ondertekeningssleutel van 64 tekens) en het events-endpoint.

Configuratie

Open Modules > Modulebeheer > DataFirefly Server-Side > Configureren. Het formulier telt vijf instellingen:

• Tracking inschakelen: de hoofdschakelaar. Zolang die op Nee staat, wordt geen enkele gebeurtenis verzonden.
• Tenant ID: de identifier van uw winkel in de dienst, gekopieerd uit uw klantomgeving.
• HMAC-secret: de ondertekeningssleutel van 64 tekens. Elke gebeurtenis wordt vóór verzending met deze sleutel ondertekend.
• Events endpoint: de ingest-URL van de dispatcher. De standaardwaarde voldoet in vrijwel alle gevallen; wijzig ze alleen als uw klantomgeving een andere aangeeft.
• Toestemming vereisen: standaard ingeschakeld. Wanneer actief wordt de aankoop alleen doorgegeven als de bezoeker marketingtoestemming heeft verleend (zie hieronder). Schakel dit alleen uit als u de toestemming stroomopwaarts met een ander mechanisme beheert.

Sla op en ga daarna over tot de test.

De verbinding testen

Klik op Een testgebeurtenis versturen in het configuratieformulier. De module stuurt een synthetische, ondertekende page_view naar de dispatcher, zonder de echte bestellingen aan te raken.

• “Testgebeurtenis bezorgd” (HTTP 200): uw Tenant ID, uw secret en uw endpoint zijn correct. Uw winkel is verbonden, ook als er aan dienstzijde nog geen enkele bestemming is geconfigureerd.
• “Testgebeurtenis mislukt”: de HTTP-code en de melding van de dispatcher worden getoond voor de diagnose (zie Probleemoplossing).

De toestemming (AVG)

Wanneer Toestemming vereisen actief is, leest de module, rechtstreeks aan serverzijde op het moment van de orderbevestiging, het toestemmingscookie in tarteaucitron-formaat dat door onze module DataFirefly Cookie Manager (Google Consent Mode v2) is geplaatst. De cookienaam wordt automatisch overgenomen uit de configuratie van de Cookie Manager (standaard tarteaucitron).

De aankoop wordt doorgegeven als de bezoeker toestemming heeft gegeven voor minstens één advertentiedienst: Meta Pixel, Google Ads, TikTok Pixel of LinkedIn Insight. De aanpak is privacy-first: cookie afwezig of onleesbaar = geen verzending.

Beheert u de toestemming met een ander mechanisme, schakel dan Toestemming vereisen uit en pas uw eigen logica stroomopwaarts toe: het is dan aan uw mechanisme om te garanderen dat geen enkele bestelling van een niet-toestemmende bezoeker afkomstig is.

Wat er wordt verzonden

Bij elke bevestigde bestelling bouwt de module een purchase-gebeurtenis op met:

• Transactie: betaald bedrag, ISO-valuta, bestelreferentie, producten (id, naam, aantal, eenheidsprijs incl. btw) en totaal aantal artikelen.
• Matchinggegevens: e-mail en klant-ID, telefoon, voornaam, achternaam, plaats, postcode en ISO-land van het factuuradres (terugval op het leveringsadres).
• Browseridentifiers vastgelegd op het moment van de bestelling: _fbp en _fbc (Meta), _ttp (TikTok) en het GA4-client-ID uit het cookie _ga.

Elk optioneel veld wordt alleen toegevoegd als het aanwezig en geldig is: de dispatcher valideert strikt, en een goedgevormde gebeurtenis is een bezorgde gebeurtenis. De gebeurtenis-identifier is gekoppeld aan de bestelling (order_ID), idempotent: die maakt de client + server-deduplicatie aan platformzijde mogelijk als u ook browsertags gebruikt.

Aan transportzijde draagt elke request drie headers: de tenant, de tijdstempel (geverifieerd in een anti-replayvenster van 300 seconden) en de HMAC-SHA256-handtekening van de exacte requestbody. Uw Meta-, GA4-, TikTok-, Pinterest- en Google Ads-credentials blijven in uw DataFirefly-omgeving: noch de winkel, noch de browser ziet ze.

Uw gebeurtenissen opvolgen aan dienstzijde

In uw klantomgeving toont de Event Inspector de gebeurtenissen één voor één, met gemaskeerde persoonsgegevens (AVG-conform). U controleert er wat daadwerkelijk aan elke bestemming wordt geleverd. De beschikbaarheid van de platformen is op elk moment raadpleegbaar op de publieke statuspagina.

Probleemoplossing

De testgebeurtenis mislukt met “not_configured”

Een van de drie velden (Tenant ID, secret, endpoint) is leeg. Kopieer de drie waarden opnieuw uit uw klantomgeving en sla op voordat u opnieuw test.

De testgebeurtenis mislukt met HTTP 401 of 403

De handtekening wordt geweigerd: het HMAC-secret komt niet overeen met de tenant, of het Tenant ID is fout. Kopieer beide waarden opnieuw, zonder spatie of regeleinde. Controleer ook of de klok van uw server correct is (NTP): een afwijking van meer dan 300 seconden laat het anti-replayvenster mislukken.

De testgebeurtenis mislukt met “curl: …” of HTTP 0

Uw server kan de dispatcher niet bereiken: uitgaande firewall, DNS of proxy. Sta uitgaande HTTPS-verbindingen toe naar het endpoint dat in uw klantomgeving staat.

De test slaagt, maar er komt geen enkele bestelling aan

• Controleer of Tracking inschakelen daadwerkelijk op Ja staat.
• Is Toestemming vereisen actief, dan worden alleen bestellingen doorgegeven van bezoekers die met een advertentiedienst hebben ingestemd. Plaats een testbestelling nadat u de advertentiecookies in de banner hebt geaccepteerd.
• Raadpleeg Geavanceerde instellingen > Logboeken in de backoffice: elke bezorgingsfout wordt er gelogd met de HTTP-code en het bestel-ID (voorvoegsel [DataFirefly SS]).

De conversies worden dubbel geteld

Onmogelijk aan modulezijde: de gebeurtenis-identifier is idempotent per bestelling. Gebruikt u daarnaast browsertags buiten de dienst om, zorg er dan voor dat die dezelfde gebeurtenis-identifier (order_ID) versturen zodat de platformen dedupliceren.

De-installatie

De de-installatie verwijdert de volledige configuratie van de module (tenant, secret, endpoint, instellingen). Er wordt geen enkele tabel in de database aangemaakt: de module slaat niets anders op dan zijn configuratie.