DataFirefly Server-Side per Shopware — Guida completa

Panoramica

DataFirefly Server-Side è il connettore Shopware gratuito del servizio DataFirefly Server-Side Tracking. A ogni ordine confermato, il plugin costruisce un evento di acquisto completo e lo invia da server a server, firmato con HMAC-SHA256, verso il dispatcher DataFirefly ospitato nell’UE. Il servizio ingerisce l’evento, lo deduplica e lo diffonde verso le tue destinazioni: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API e Google Ads.

Il plugin è volutamente minimale lato negozio: non memorizza alcuna credenziale di destinazione, non aggiunge alcuno script allo storefront, non crea alcuna tabella. Cattura, costruisce, firma, invia — il resto avviene lato servizio.

Requisiti

• Shopware 6.5.x, 6.6.x o 6.7.x (installazione self-hosted — Shopware Cloud non accetta plugin server)
• PHP 8.1 o superiore, in base alla tua versione di Shopware, con l’estensione curl
• Un abbonamento attivo al servizio DataFirefly Server-Side Tracking per ottenere la tua chiave di connessione

Installazione

Caricando lo ZIP

1. Nell’amministrazione Shopware, apri Estensioni → Le mie estensioni → Carica estensione e seleziona il file ZIP del plugin.
2. Clicca su Installa, poi su Attiva.

Da riga di comando

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

Connessione al servizio

Ottenere la chiave di connessione

1. Accedi alla tua area cliente su server-side.datafirefly.com.
2. Apri la sezione Collega il tuo negozio.
3. Copia la chiave di connessione in una riga, nel formato dfss_…. Codifica il tuo identificativo tenant, il tuo secret di firma HMAC e l’endpoint di ingestione.

Incollare la chiave in Shopware

1. Apri Estensioni → Le mie estensioni → DataFirefly Server-Side → Configurazione.
2. Incolla la chiave nel campo Chiave di connessione.
3. Attiva l’interruttore Attiva tracking e salva.

Tutto qui: dal prossimo ordine confermato, l’evento di acquisto parte verso il dispatcher. Una chiave assente o malformata non è mai un errore bloccante — il plugin si considera semplicemente non configurato e non invia nulla.

Configurazione

• Attiva tracking — interruttore principale. Disattivato di default.
• Chiave di connessione — la chiave dfss_… copiata dalla tua area cliente.
• Richiedi consenso marketing — attiva il gate di consenso (disattivato di default, vedi sotto).
• Nome del cookie di consenso — il cookie depositato dal tuo strumento di consenso (CMP).
• Valore del cookie di consenso (contiene) — opzionale: frammento di valore atteso nel cookie.

La configurazione è gestita per sales channel: puoi attivare il tracking su un negozio e non su un altro, o usare chiavi diverse per canale.

Gate di consenso

Il core di Shopware non deposita nativamente un cookie unico di consenso marketing leggibile lato server. Il plugin offre quindi un gate generico, disattivato di default: quando è attivo, l’evento di acquisto viene inviato solo se il cookie configurato è presente nella richiesta del cliente — e, se è definito un valore atteso, solo se il valore del cookie lo contiene.

Con DataFirefly Cookie Consent

La combinazione consigliata su Shopware è il nostro plugin DataFirefly Cookie Consent (banner conforme al GDPR con Google Consent Mode v2 nativo): attiva il gate e indica il nome del cookie di consenso depositato dal banner (indicato nella sua documentazione). Il rifiuto o l’assenza del consenso marketing blocca l’invio, lato server, prima di qualsiasi trasmissione.

Con un altro CMP

Indica il nome del cookie che il tuo CMP deposita quando il visitatore accetta i cookie di marketing (per esempio CookieConsent per Cookiebot), e opzionalmente un frammento di valore (per esempio marketing:true). Se il tuo CMP non deposita un cookie leggibile lato server, o se gestisci il consenso interamente a monte, lascia il gate disattivato.

Comportamento privacy-first

• Gate attivo + nome cookie non configurato → non parte nulla.
• Gate attivo + cookie assente o vuoto → non parte nulla.
• Gate attivo + valore atteso configurato ma assente dal valore del cookie → non parte nulla.
• Nessuna richiesta disponibile (flussi CLI o headless senza richiesta HTTP) → non parte nulla.

Testare la connessione

Il plugin include un comando console che invia un page_view sintetico verso il dispatcher, senza toccare ordini reali:

bin/console datafirefly:serverside:test

Opzioni disponibili:

• --sales-channel-id=<id> — legge la configurazione di un sales channel specifico (default: configurazione globale).
• --source-url=<url> — include una sourceUrl nell’evento di test.

Un codice HTTP 2xx conferma che la chiave di connessione, la firma e l’endpoint sono corretti — anche se nessuna destinazione è ancora configurata lato servizio.

Funzionamento tecnico

L’evento purchase

Il plugin si iscrive all’evento di ordine confermato di Shopware. A ogni attivazione, costruisce un evento purchase con un identificativo idempotente basato sull’ordine (order_<id>): se usi anche tag nel browser, il servizio applica la deduplicazione client + server e ogni conversione viene contata una sola volta.

Dati inviati

• Transazione: valore pagato, valuta, numero d’ordine, prodotti, quantità, numero di articoli.
• Corrispondenza: e-mail, identificativo cliente, telefono, nome, cognome, città, CAP e paese dell’indirizzo di fatturazione.
• Identificatori del browser catturati al momento dell’ordine: _fbp, _fbc, _ttp e il client id GA4 (cookie _ga).

La costruzione è difensiva: ogni campo opzionale viene aggiunto solo se presente e valido (il dispatcher valida in modo rigoroso — paese di 2 caratteri, valuta di 3, ecc.). Nei flussi headless dove alcune associazioni dell’ordine possono mancare, i campi corrispondenti vengono semplicemente omessi, mai fabbricati.

Firma HMAC

Ogni evento è firmato con HMAC-SHA256 usando il secret del tuo tenant: i byte firmati sono esattamente i byte inviati, con un timestamp verificato in una finestra anti-replay di 300 secondi. Gli header trasmessi sono l’identificativo tenant, il timestamp e la firma. Le tue credenziali Meta, GA4, TikTok, Pinterest e Google Ads restano lato servizio — mai nel negozio, mai nel browser.

Fail-safe

L’intero sottosistema è progettato per non impattare mai il checkout: timeout di 2 secondi (connessione) e 4 secondi (totale), tutti gli errori catturati e registrati come warning nei log di Shopware con il codice HTTP e il numero d’ordine — nessuna eccezione raggiunge mai il funnel d’acquisto.

Risoluzione dei problemi

• Nessun evento parte — verifica che l’interruttore sia attivo per il sales channel giusto, che la chiave inizi con dfss_ senza spazi né interruzioni di riga, e che il gate di consenso non sia attivo senza cookie configurato.
• Il comando di test fallisce — un codice 0 con un messaggio curl indica un problema di rete in uscita (firewall); un 401/403 indica una chiave non valida o rigenerata: copiala di nuovo dalla tua area cliente.
• Eventi segnati come non consegnati nei log — il codice HTTP e il numero d’ordine vengono registrati nei log di Shopware (canale warning). Un codice 4xx significa che il payload è stato rifiutato dalla validazione rigorosa del dispatcher; controlla l’Event Inspector della tua area cliente per i dettagli.
• Conversioni duplicate su Meta o GA4 — assicurati che i tuoi tag browser inviino lo stesso identificativo di evento (order_<id>) per beneficiare della deduplicazione.

Changelog

• 1.0.0 (01/07/2026) — versione iniziale: evento purchase server-side idempotente, firma HMAC-SHA256 con finestra anti-replay, chiave di connessione in una riga, gate di consenso opt-in tramite cookie del CMP, configurazione per sales channel, comando console di test, progettazione fail-safe.