# DataFirefly Server-Side — Guida completa

> Guida completa all'installazione, connessione e utilizzo del connettore gratuito DataFirefly Server-Side per WooCommerce: tracking client + server, deduplicazione, acquisto in server-side, consenso e abbonamento al servizio.

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

DataFirefly Server-Side è il connettore WooCommerce **gratuito** del servizio _DataFirefly Server-Side Tracking_. Il plugin cattura gli eventi del tuo negozio e li firma; il servizio li diffonde lato server verso le tue piattaforme pubblicitarie e di analisi. Questa guida copre l'installazione, la connessione, il funzionamento del funnel client + server, la deduplicazione, il purchase lato server, la scelta delle destinazioni client, la gestione del consenso, l'affidabilità e l'abbonamento.

**Modello plugin gratuito + servizio a pagamento.** Il plugin non costa nulla e resterà gratuito. Per _inviare_ davvero i tuoi eventi serve un abbonamento al servizio DataFirefly Server-Side (da 39 €/mese), che si occupa dell'ingestione e della diffusione in server-side.

## Requisiti

- WordPress 5.8 o successivi
- WooCommerce 5.0 o successivi (compatibile con HPOS — High-Performance Order Storage)
- PHP 7.4 o successivi
- Un cron WordPress funzionante (o un vero cron di sistema) per la coda di ritentativi e l'invio differito
- Un abbonamento DataFirefly Server-Side per ottenere la tua chiave di connessione

## Installazione

1. Scarica il file `datafirefly-serverside-2_2_0.zip` dalla tua area cliente DataFirefly.
2. Nel back-office di WordPress, vai su **Plugin → Aggiungi nuovo → Carica plugin**, seleziona lo ZIP e fai clic su _Installa ora_.
3. Attiva il plugin. Un nuovo menu **DataFirefly Server-Side** appare nell'amministrazione.

## Connessione con una chiave

Il plugin si configura con una sola chiave di connessione, che attiva contemporaneamente il tracking lato client e lato server.

1. Dalla tua area cliente DataFirefly, copia la **chiave di connessione** (inizia con `dfss_`).
2. Incollala nel campo previsto della schermata _Connessione_ del plugin.
3. Fai clic su **Connetti**. Il plugin attiva il tracking client e server, invia un evento di test al dispatcher e imposta i tag client per le destinazioni configurate.
4. Verifica che lo stato passi a **Connesso ✓** e usa il pulsante _Invia evento di test_ per confermare la consegna.

La chiave `dfss_…` codifica il tuo tenant, un segreto e l'endpoint del dispatcher. È limitata agli host `datafirefly.com` in HTTPS: una chiave che punta a un altro dominio viene rifiutata.

### Modalità avanzata (inserimento manuale)

Se preferisci non usare la chiave unica, la **modalità avanzata** consente di inserire manualmente tenant, segreto ed endpoint. Riservala alle configurazioni specifiche: la modalità a chiave unica copre quasi tutti i casi.

## Funnel completo client + server

Il plugin segue tutto il funnel lato browser, mentre la conversione di acquisto parte lato server.

- **Lato browser:** `page_view`, `view_content` (visualizzazione prodotto), `add_to_cart`, `initiate_checkout` e `add_payment_info`.
- **Lato server:** `purchase`, attivato dagli hook dell'ordine WooCommerce.

Le due parti condividono lo stesso identificatore di evento per consentire la deduplicazione.

### Eventi di merchandising (dalla v2.1.1)

Il tracker copre anche il merchandising del tuo catalogo: `view_item_list` (visualizzazione di un elenco di prodotti — categoria, risultati di ricerca), `select_item` (clic su un prodotto di un elenco), `view_promotion` e `select_promotion` (visualizzazione e clic di una promozione). Il contesto associato — identificatore e nome dell'elenco, identificatore e nome della promozione, creatività e posizionamento — è trasmesso al server-side per arricchire le tue analisi di percorso.

### Deduplicazione per event_id

Per ogni ordine, l'evento client e l'evento server portano lo stesso `event_id`, costruito sull'identificatore dell'ordine (per esempio `order_1042`). Meta, GA4 e le altre piattaforme si basano su di esso per **contare ogni conversione una sola volta**. Recuperi così le conversioni che il browser lascia sfuggire, senza doppio conteggio.

## Scegliere le destinazioni client (Meta, GA4, TikTok)

Dalla versione 2.2.0, ogni tag client si attiva o disattiva singolarmente nelle impostazioni del plugin, riga **Destinazioni client**:

- **Meta** (pixel Facebook, `fbevents.js`)
- **Google Analytics 4** (`gtag.js`)
- **TikTok** (pixel TikTok)

Una destinazione deselezionata **non carica mai il suo script di terze parti** nel browser dei tuoi visitatori e **non imposta mai i suoi cookie**. Non usi Meta? Deselezionalo: meno JavaScript, meno richieste, una pagina più veloce e più leggera. Le destinazioni non configurate sul tuo account DataFirefly sono segnalate nella schermata delle impostazioni.

Queste caselle riguardano solo i _tag client_. La diffusione server-side verso Meta CAPI, GA4, TikTok, Pinterest e Google Ads resta governata dalla configurazione del tuo account nell'area cliente DataFirefly. Nota che disattivando GA4 il plugin non imposta più il cookie `_ga`, il che riduce la qualità di corrispondenza GA4 lato server — coerente se non usi GA4.

## Purchase server-side: affidabile e non falsificabile

La conversione di acquisto è attivata dagli hook dell'ordine WooCommerce (pagamento completato, in lavorazione, completato), in modo **idempotente**: un blocco (`_dfss_sent`) garantisce che uno stesso acquisto non venga mai inviato due volte, anche se si attivano più hook.

- Poiché l'evento parte dal server, nessun ad-blocker né ITP può impedirlo.
- Al contrario, l'endpoint pubblico di raccolta (beacon) **esclude volutamente** l'evento `purchase`: è impossibile iniettare un falso acquisto dal browser per gonfiare i tuoi ricavi Meta o GA4.
- Il contesto dell'evento (valore, valuta, prodotti) è autoritativo lato server: il browser non «indovina» nulla.

Per rendere affidabile l'attribuzione anche tramite un gateway di pagamento con reindirizzamento, il plugin cattura al checkout i cookie `_fbp`, `_fbc`, `_ga`, `_ttp` e li associa all'ordine, e imposta cookie first-party di click-id (90 giorni) per trasportare `fbc`, `ttclid` e `gclid` fino all'acquisto.

## Gestione del consenso

Il **gate di consenso è attivo per impostazione predefinita**: nulla viene inviato finché non viene concesso il consenso marketing.

### Compatibilità nativa con Cookie Consent v2

Il plugin rileva in modo nativo il modulo **DataFirefly Cookie Consent — GDPR & Google Consent Mode v2** e ne legge il cookie di consenso (`dfcc_consent`) direttamente lato server. Se la categoria _marketing_ viene rifiutata, l'evento viene scartato, qualunque cosa affermi il browser. È la combinazione consigliata: banner, Consent Mode v2 e tracking server-side parlano la stessa lingua.

### Altre soluzioni di consenso

In mancanza di Cookie Consent v2, il plugin gestisce anche **WP Consent API**, **Complianz**, **Cookiebot** e **IAB TCF v2**. Puoi mantenere il tuo banner attuale e collegarvi il tracking.

## Affidabilità: coda di ritentativi e registro di attività

Un evento che non è stato possibile consegnare non è perso: viene messo in coda e **reinviato automaticamente** da un cron ogni 5 minuti.

Il **registro di attività** mostra in tempo reale, senza gergo, ciò che è stato consegnato, ciò che è in coda e ciò che è stato rifiutato, con il codice HTTP e il numero di tentativi. È il tuo primo riflesso diagnostico.

Il cron di WordPress si esegue solo con il traffico. Su un negozio a basso traffico, configura un vero cron di sistema che chiami `wp-cron.php` affinché la coda di ritentativi si svuoti regolarmente.

## Sicurezza

- Nessun segreto nel browser: lato client vengono esposti solo identificatori pubblici (pixel, measurement id).
- Il segreto di firma e le tue credenziali di destinazione restano lato server.
- Ogni evento è firmato con HMAC prima di raggiungere il dispatcher, ospitato nell'UE (Germania).
- Il plugin è distribuito con licenza GPLv2 o successiva e segue gli standard di codifica di WordPress.

## Abbonamento al servizio DataFirefly Server-Side

Il plugin cattura e firma; il servizio _DataFirefly Server-Side Tracking_ ingerisce e diffonde lato server verso cinque destinazioni: **Meta CAPI, GA4 (Measurement Protocol), TikTok Events API, Pinterest Conversions API e Google Ads**. Il dispatcher è ospitato in Germania, l'ingestione è firmata con HMAC, i dati personali sono mascherati e l'attivazione rispetta il consenso. Una sola integrazione, una fattura consolidata, più siti possibili.

Scopri i piani e abbonati su [server-side.datafirefly.com](https://server-side.datafirefly.com/):

- **Starter** — 39 €/mese: 1 sito, fino a 500 K eventi
- **Growth** — 119 €/mese: 5 siti, fino a 2 M eventi
- **Scale** — 349 €/mese: 20 siti, fino a 10 M eventi

## Risoluzione dei problemi

### Lo stato resta su «Non connesso»

Verifica che la chiave inizi con `dfss_` e che sia stata copiata per intero. Una chiave che punta a un dominio diverso da `datafirefly.com` (HTTPS) viene rifiutata. Riprova con il pulsante _Invia evento di test_.

### Il purchase non arriva

Il purchase parte dagli hook dell'ordine: assicurati che l'ordine raggiunga uno stato di pagamento (completato / in lavorazione / completato). Consulta il registro di attività per vedere se l'evento è in coda o rifiutato, e controlla il cron se gli eventi ristagnano.

### Lo script Meta (o GA4, TikTok) non si carica

Due cause possibili: la destinazione è deselezionata in **Destinazioni client** (comportamento voluto dalla v2.2.0), oppure non è configurata sul tuo account DataFirefly — la schermata delle impostazioni lo indica in tal caso. Dopo una modifica lato account, usa il pulsante _Aggiorna identificatori di destinazione_.

### Conversioni contate due volte

Verifica che nessun altro plugin di tracking invii già un `purchase` concorrente senza `event_id` condiviso. Con il solo DataFirefly Server-Side, l'`event_id` basato sull'ordine garantisce la deduplicazione.

### Nulla parte anche se il consenso sembra concesso

Il gate è attivo per impostazione predefinita. Verifica che la categoria _marketing_ sia effettivamente accettata nella tua soluzione di consenso, e che questa venga rilevata (Cookie Consent v2, WP Consent API, Complianz, Cookiebot o IAB TCF v2).

Hai bisogno di aiuto? Contatta il supporto DataFirefly dalla tua area cliente allegando una schermata del registro di attività (codice HTTP + numero di tentativi).