# DataFirefly Server-Side — Guida completa

> Guida completa al modulo gratuito DataFirefly Server-Side per PrestaShop 8 e 9: installazione, credenziali, evento di test, gate di consenso con il Cookie Manager e risoluzione dei problemi.

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

## Panoramica

DataFirefly Server-Side è il connettore PrestaShop gratuito del servizio [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/en/). A ogni ordine convalidato, il modulo costruisce un evento di acquisto completo e lo invia da server a server, firmato HMAC-SHA256, verso il dispatcher DataFirefly ospitato nell'UE (Germania). Il servizio consegna poi l'evento alle destinazioni configurate: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API e Google Ads.

La divisione dei ruoli è semplice: il modulo **cattura e firma**, il servizio **ingerisce, deduplica e consegna**. Il modulo è gratuito; la consegna richiede un abbonamento al servizio (Starter da 39 €/mese).

Un incidente di tracciamento non romperà mai il vostro checkout: il modulo è fail-safe per progettazione (timeout di 2 s / 4 s, errori registrati nei log di PrestaShop, nessuna eccezione raggiunge mai il funnel d'ordine).

## Requisiti

- PrestaShop 1.7.6 o superiore, 8.x o 9.x
- PHP 7.4 o superiore, con l'estensione cURL (presente su quasi tutti gli hosting)
- Un account DataFirefly Server-Side Tracking attivo — abbonatevi su [server-side.datafirefly.com](https://server-side.datafirefly.com/en/)
- Consigliato: il nostro modulo [DataFirefly Cookie Manager](https://www.datafirefly.com/product/cookie-manager-tarteaucitron-conformite-rgpd-cle-en-main-pour-prestashop/) (banner tarteaucitron conforme con Google Consent Mode v2) per il gate di consenso nativo

## Installazione

1. Scaricate lo ZIP del modulo dal vostro account DataFirefly.
2. Nel back office di PrestaShop, aprite **Moduli > Gestore moduli > Carica un modulo** e trascinate il file `datafirefly_serverside.zip`.
3. Fate clic su **Installa**. Il modulo si registra sull'hook di convalida dell'ordine; non servono override né modifiche al tema.

All'installazione, il tracciamento è **disattivato** e il requisito di consenso è **attivato**: nulla viene inviato finché non configurate e attivate il modulo.

## Ottenere le credenziali

1. Accedete al vostro [spazio cliente DataFirefly](https://admin.datafirefly.com/app/login) (o [abbonatevi](https://admin.datafirefly.com/pricing) se non l'avete ancora fatto).
2. Aprite la sezione **Collega il tuo negozio** del vostro sito.
3. Copiate i tre valori mostrati: il **Tenant ID** (nel formato `shop_vostronegozio_xxxx`), il **secret HMAC** (chiave di firma di 64 caratteri) e l'**endpoint degli eventi**.

Il secret HMAC è una chiave privata: non condividetelo e non incollatelo da nessuna parte tranne che nella configurazione del modulo. In caso di fuga, rigeneratelo dal vostro spazio cliente.

## Configurazione

Aprite **Moduli > Gestore moduli > DataFirefly Server-Side > Configura**. Il modulo ha cinque impostazioni:

- **Attiva il tracciamento** — l'interruttore principale. Finché è su No, nessun evento viene inviato.
- **Tenant ID** — l'identificativo del vostro negozio nel servizio, copiato dal vostro spazio cliente.
- **Secret HMAC** — la chiave di firma di 64 caratteri. Ogni evento viene firmato con questa chiave prima dell'invio.
- **Events endpoint** — l'URL di ingestione del dispatcher. Il valore predefinito va bene in quasi tutti i casi; modificatelo solo se il vostro spazio cliente ne indica un altro.
- **Richiedi consenso** — attivo per impostazione predefinita. Quando è attivo, l'acquisto viene trasmesso solo se il visitatore ha concesso il consenso marketing (vedi sotto). Disattivatelo solo se gestite il consenso a monte con un altro sistema.

Salvate e passate al test.

## Testare la connessione

Fate clic su **Invia evento di test** nel modulo di configurazione. Il modulo invia un `page_view` sintetico, firmato, al dispatcher — senza toccare gli ordini reali.

- **«Evento di test consegnato» (HTTP 200)**: il vostro Tenant ID, il secret e l'endpoint sono corretti. Il negozio è collegato, anche se lato servizio non è ancora configurata nessuna destinazione.
- **«Evento di test fallito»**: il codice HTTP e il messaggio del dispatcher vengono mostrati per la diagnosi (vedi Risoluzione dei problemi).

## Il consenso (GDPR)

Quando **Richiedi consenso** è attivo, il modulo legge — direttamente lato server, al momento della convalida dell'ordine — il cookie di consenso in formato tarteaucitron depositato dal nostro modulo [DataFirefly Cookie Manager](https://www.datafirefly.com/product/cookie-manager-tarteaucitron-conformite-rgpd-cle-en-main-pour-prestashop/) (Google Consent Mode v2). Il nome del cookie viene ripreso automaticamente dalla configurazione del Cookie Manager (predefinito `tarteaucitron`).

L'acquisto viene trasmesso se il visitatore ha acconsentito ad **almeno un servizio pubblicitario**: Meta Pixel, Google Ads, TikTok Pixel o LinkedIn Insight. L'approccio è privacy-first: cookie assente o illeggibile = nessun invio.

È la combinazione consigliata su PrestaShop: il Cookie Manager gestisce il banner, il Consent Mode v2 e la prova del consenso; questo modulo applica la stessa decisione al tracciamento server-side. Un'unica fonte di verità per tutta la catena.

Se gestite il consenso con un altro sistema, disattivate **Richiedi consenso** e applicate la vostra logica a monte: sarà allora il vostro sistema a garantire che nessun ordine provenga da un visitatore non consenziente.

## Cosa viene inviato

A ogni ordine convalidato, il modulo costruisce un evento `purchase` con:

- **Transazione**: importo pagato, valuta ISO, riferimento dell'ordine, prodotti (id, nome, quantità, prezzo unitario IVA inclusa) e numero totale di articoli.
- **Dati di corrispondenza**: e-mail e id cliente, telefono, nome, cognome, città, CAP e paese ISO dell'indirizzo di fatturazione (con l'indirizzo di consegna come riserva).
- **Identificatori del browser** catturati al momento dell'ordine: `_fbp` e `_fbc` (Meta), `_ttp` (TikTok) e il client id GA4 estratto dal cookie `_ga`.

Ogni campo opzionale viene aggiunto solo se presente e valido: il dispatcher convalida in modo rigoroso, e un evento ben formato è un evento consegnato. L'identificativo dell'evento è legato all'ordine (`order_ID`), in modo idempotente — è ciò che consente la deduplicazione client + server sulle piattaforme se usate anche tag browser.

Sul trasporto, ogni richiesta porta tre header: il tenant, il timestamp (verificato in una finestra anti-replay di 300 secondi) e la firma HMAC-SHA256 del corpo esatto della richiesta. Le vostre credenziali Meta, GA4, TikTok, Pinterest e Google Ads restano nel vostro spazio DataFirefly: né il negozio né il browser le vedono.

## Monitorare gli eventi lato servizio

Nel vostro spazio cliente, l'**Event Inspector** mostra gli eventi uno per uno, con i dati personali mascherati (conforme al GDPR). È lì che verificate cosa viene realmente consegnato a ciascuna destinazione. La disponibilità delle piattaforme è consultabile in qualsiasi momento sulla [pagina di stato pubblica](https://serverside.datafirefly.com/status).

## Risoluzione dei problemi

### L'evento di test fallisce con «not_configured»

Uno dei tre campi (Tenant ID, secret, endpoint) è vuoto. Ricopiate i tre valori dal vostro spazio cliente e salvate prima di riprovare.

### L'evento di test fallisce con HTTP 401 o 403

La firma è rifiutata: il secret HMAC non corrisponde al tenant, o il Tenant ID è errato. Ricopiate entrambi i valori senza spazi né a capo. Verificate anche che l'orologio del server sia corretto (NTP): uno scarto superiore a 300 secondi fa fallire la finestra anti-replay.

### L'evento di test fallisce con «curl: …» o HTTP 0

Il vostro server non riesce a raggiungere il dispatcher: firewall in uscita, DNS o proxy. Autorizzate le connessioni HTTPS in uscita verso l'endpoint indicato nel vostro spazio cliente.

### Il test passa, ma non arriva nessun ordine

- Verificate che **Attiva il tracciamento** sia su Sì.
- Se **Richiedi consenso** è attivo, vengono trasmessi solo gli ordini di visitatori che hanno acconsentito a un servizio pubblicitario. Effettuate un ordine di prova dopo aver accettato i cookie pubblicitari nel banner.
- Consultate **Parametri avanzati > Log** nel back office: ogni errore di consegna vi è registrato con il codice HTTP e l'id dell'ordine (prefisso `[DataFirefly SS]`).

### Le conversioni vengono contate due volte

Impossibile lato modulo: l'identificativo dell'evento è idempotente per ordine. Se usate anche tag browser al di fuori del servizio, assicuratevi che inviino lo stesso identificativo di evento (`order_ID`) affinché le piattaforme deduplichino.

## Disinstallazione

La disinstallazione rimuove tutta la configurazione del modulo (tenant, secret, endpoint, impostazioni). Nessuna tabella viene creata nel database: il modulo non memorizza nient'altro che la sua configurazione.