# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/datafirefly-server-side-shopware/>
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-server-side-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-server-side-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-server-side-shopware/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## Panoramica

DataFirefly Server-Side è il connettore Shopware gratuito del servizio [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). 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.

**Modello economico:** il plugin è gratuito; la diffusione degli eventi richiede un abbonamento al servizio (Starter 39 €/mese, Growth 119 €/mese, Scale 349 €/mese). Dettagli e iscrizione su [server-side.datafirefly.com](https://server-side.datafirefly.com/).

## 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
```

Il plugin non aggiunge nulla allo storefront: nessun `build-storefront` è necessario dopo l'installazione.

## Connessione al servizio

### Ottenere la chiave di connessione

1. Accedi alla tua area cliente su [server-side.datafirefly.com](https://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.

La chiave di connessione contiene il tuo secret di firma: mantienila riservata, come una password. In caso di fuga, rigenerala dalla tua area cliente e sostituiscila nella configurazione del plugin.

### 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](https://www.datafirefly.com/it/product/df-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.

Nel dubbio, il plugin non invia: è una scelta di progettazione. Nessun evento può partire «per sbaglio» senza consenso finché il gate è attivo.

## 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=` — legge la configurazione di un sales channel specifico (default: configurazione globale).
- `--source-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_`): 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_`) 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.