DataFirefly Server-Side — Guida completa

Panoramica

DataFirefly Server-Side è il connettore PrestaShop gratuito del servizio DataFirefly Server-Side Tracking. 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).

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
• Consigliato: il nostro modulo DataFirefly Cookie Manager (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 (o abbonatevi 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.

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 (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.

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.

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.