DataFirefly Server-Side pour Shopware — Guide complet

Présentation

DataFirefly Server-Side est le connecteur Shopware gratuit du service DataFirefly Server-Side Tracking. À chaque commande validée, le plugin construit un événement d’achat complet et l’envoie de serveur à serveur, signé HMAC-SHA256, vers le dispatcher DataFirefly hébergé dans l’UE. Le service ingère l’événement, le déduplique et le diffuse vers vos destinations : Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API et Google Ads.

Le plugin est volontairement minimaliste côté boutique : aucune credential de destination n’y est stockée, aucun script n’est ajouté au storefront, aucune table n’est créée. Il capte, construit, signe, envoie — le reste se passe côté service.

Prérequis

• Shopware 6.5.x, 6.6.x ou 6.7.x (installation auto-hébergée — Shopware Cloud n’accepte pas les plugins serveur)
• PHP 8.1 ou supérieur, selon votre version de Shopware, avec l’extension curl
• Un abonnement actif au service DataFirefly Server-Side Tracking pour obtenir votre clé de connexion

Installation

Par upload de ZIP

1. Dans l’administration Shopware, ouvrez Extensions → Mes extensions → Télécharger l’extension et sélectionnez le fichier ZIP du plugin.
2. Cliquez sur Installer, puis Activer.

Via la ligne de commande

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

Connexion au service

Obtenir votre clé de connexion

1. Connectez-vous à votre espace client sur server-side.datafirefly.com.
2. Ouvrez la section Connecter votre boutique.
3. Copiez la clé de connexion en une ligne, au format dfss_…. Elle encode votre identifiant tenant, votre secret de signature HMAC et l’endpoint d’ingestion.

Coller la clé dans Shopware

1. Ouvrez Extensions → Mes extensions → DataFirefly Server-Side → Configuration.
2. Collez la clé dans le champ Clé de connexion.
3. Activez le toggle Activer le tracking et enregistrez.

C’est tout : dès la prochaine commande validée, l’événement d’achat part vers le dispatcher. Une clé absente ou mal formée n’est jamais une erreur bloquante — le plugin considère simplement qu’il n’est pas configuré et n’envoie rien.

Configuration

• Activer le tracking — interrupteur principal. Désactivé par défaut.
• Clé de connexion — la clé dfss_… copiée depuis votre espace client.
• Exiger le consentement marketing — active la gate de consentement (désactivée par défaut, voir ci-dessous).
• Nom du cookie de consentement — le cookie déposé par votre outil de consentement (CMP).
• Valeur du cookie de consentement (contient) — optionnel : fragment de valeur attendu dans le cookie.

La configuration est gérée par sales channel : vous pouvez activer le tracking sur une boutique et pas sur une autre, ou utiliser des clés différentes par canal.

Gate de consentement

Shopware ne pose pas nativement de cookie unique de consentement marketing lisible côté serveur. Le plugin propose donc une gate générique, désactivée par défaut : lorsqu’elle est active, l’événement d’achat n’est envoyé que si le cookie configuré est présent dans la requête du client — et, si une valeur attendue est renseignée, que si la valeur du cookie la contient.

Avec DataFirefly Cookie Consent

La combinaison recommandée sur Shopware est notre plugin DataFirefly Cookie Consent (bandeau RGPD/CNIL avec Google Consent Mode v2 natif) : activez la gate et renseignez le nom du cookie de consentement déposé par le bandeau (indiqué dans sa documentation). Le refus ou l’absence de consentement marketing bloque l’envoi, côté serveur, avant toute transmission.

Avec un autre CMP

Renseignez le nom du cookie que votre CMP dépose lorsque le visiteur accepte les cookies marketing (par exemple CookieConsent pour Cookiebot), et éventuellement un fragment de valeur (par exemple marketing:true). Si votre CMP ne pose pas de cookie lisible côté serveur, ou si vous gérez le consentement entièrement en amont, laissez la gate désactivée.

Comportement privacy-first

• Gate active + nom de cookie non configuré → rien ne part.
• Gate active + cookie absent ou vide → rien ne part.
• Gate active + valeur attendue configurée mais absente de la valeur du cookie → rien ne part.
• Requête absente (flux CLI ou headless sans requête HTTP) → rien ne part.

Tester la connexion

Le plugin fournit une commande console qui envoie un page_view synthétique vers le dispatcher, sans toucher aux vraies commandes :

bin/console datafirefly:serverside:test

Options disponibles :

• --sales-channel-id=<id> — lit la configuration d’un sales channel spécifique (par défaut : configuration globale).
• --source-url=<url> — inclut une sourceUrl dans l’événement de test.

Un code HTTP 2xx confirme que la clé de connexion, la signature et l’endpoint sont corrects — même si aucune destination n’est encore configurée côté service.

Fonctionnement technique

L’événement purchase

Le plugin s’abonne à l’événement de commande validée de Shopware. À chaque déclenchement, il construit un événement purchase avec un identifiant idempotent calé sur la commande (order_<id>) : si vous utilisez aussi des tags navigateur, le service applique la déduplication client + serveur et chaque conversion n’est comptée qu’une fois.

Données envoyées

• Transaction : valeur payée, devise, numéro de commande, produits, quantités, nombre d’articles.
• Correspondance : e-mail, identifiant client, téléphone, prénom, nom, ville, code postal et pays de l’adresse de facturation.
• Identifiants navigateur capturés au moment de la commande : _fbp, _fbc, _ttp et le client id GA4 (cookie _ga).

La construction est défensive : chaque champ optionnel n’est ajouté que s’il est présent et valide (le dispatcher valide strictement — pays sur 2 caractères, devise sur 3, etc.). Dans les flux headless où certaines associations de la commande peuvent manquer, les champs correspondants sont simplement omis, jamais fabriqués.

Signature HMAC

Chaque événement est signé HMAC-SHA256 avec votre secret de tenant : les octets signés sont exactement les octets envoyés, avec un horodatage vérifié dans une fenêtre de 300 secondes contre le rejeu. Les en-têtes transmis sont l’identifiant tenant, le timestamp et la signature. Vos credentials Meta, GA4, TikTok, Pinterest et Google Ads restent côté service — jamais dans la boutique, jamais dans le navigateur.

Fail-safe

Tout le sous-système est conçu pour ne jamais impacter le checkout : timeouts de 2 secondes (connexion) et 4 secondes (total), toutes les erreurs capturées et journalisées en warning dans les logs Shopware avec le code HTTP et le numéro de commande — aucune exception ne remonte jusqu’au tunnel de commande.

Dépannage

• Aucun événement ne part — vérifiez que le toggle est activé pour le bon sales channel, que la clé commence par dfss_ sans espace ni retour à la ligne, et que la gate de consentement n’est pas active sans cookie configuré.
• La commande de test échoue — un code 0 avec un message curl indique un problème réseau sortant (firewall) ; un code 401/403 indique une clé invalide ou régénérée : recopiez-la depuis votre espace client.
• Événements marqués non livrés dans les logs — le code HTTP et le numéro de commande sont journalisés dans les logs Shopware (canal warning). Un code 4xx signale un payload rejeté par la validation stricte du dispatcher ; vérifiez l’Event Inspector de votre espace client pour le détail.
• Conversions en double sur Meta ou GA4 — assurez-vous que vos tags navigateur envoient le même identifiant d’événement (order_<id>) pour bénéficier de la déduplication.

Changelog

• 1.0.0 (01/07/2026) — version initiale : événement purchase serverside idempotent, signature HMAC-SHA256 avec fenêtre anti-rejeu, clé de connexion en une ligne, gate de consentement opt-in par cookie CMP, configuration par sales channel, commande console de test, conception fail-safe.