DataFirefly Push Pro — Guida completa

DataFirefly Push Pro porta le notifiche push web native a PrestaShop 8 e 9 senza alcun servizio di terze parti tipo OneSignal né abbonamento mensile. Questa guida copre installazione, configurazione iniziale, le nove automazioni, il builder di campagne, la segmentazione, l A/B test, l attribuzione del fatturato, i topics, l inbox, i webhook e la risoluzione dei problemi.

1. Presentazione e casi d uso

Il modulo implementa nativamente il protocollo Web Push VAPID (RFC 8292) con cifratura aes128gcm lato server. Le iscrizioni sono memorizzate nel tuo database PrestaShop, gli invii partono direttamente dal tuo hosting, nessun dato transita per un servizio di terze parti.

Casi d uso tipici:

• Recupero carrelli abbandonati: tre solleciti distanziati (1 h, 24 h, 72 h) senza dipendere dall email del visitatore.
• Avvisi prodotto: di nuovo disponibile, calo di prezzo, opt-in direttamente sulla scheda prodotto.
• Transazionale: conferma d ordine, spedizione, richiesta di recensione dopo la consegna.
• Riattivazione: compleanno, clienti inattivi, riepilogo dei nuovi prodotti.
• Campagne occasionali: saldi, lanci, Black Friday, con segmentazione e A/B test.

2. Requisiti

• PrestaShop 8.0 fino a 9.x
• PHP 7.4 minimo, 8.x consigliato
• MySQL 5.7 minimo o MariaDB 10.3
• HTTPS obbligatorio: l API Web Push dei browser funziona solo su un origine sicura. Solo localhost è l eccezione per i test in sviluppo.
• Un cron esterno in grado di chiamare un URL HTTP ogni 5 minuti (cron Linux, attività pianificate dell host, cron PrestaShop nativo, etc.)
• OpenSSL attivato in PHP (usato per la generazione delle chiavi VAPID e la cifratura aes128gcm)

3. Installazione

1. Scarica lo ZIP dfpushnotifications-v1.2.0-phase3.zip dalla tua area cliente DataFirefly.
2. Back office PrestaShop → Moduli → Gestore moduli → Carica un modulo → seleziona lo ZIP.
3. Fai clic su Installa. L installazione crea 14 tabelle con prefisso ps_dfpush_*, genera un token cron univoco e registra le schede BO.
4. Appare un nuovo menu: Migliora → DataFirefly Push con 8 schede (Dashboard, Campagne, Automazioni, Coda, Iscritti, Topics, Webhook, Impostazioni).

4. Generazione delle chiavi VAPID

Le chiavi VAPID identificano il tuo server presso i push service dei browser (FCM, Mozilla autopush, Apple push). Vengono generate una sola volta e non devono mai cambiare dopo la messa in produzione (altrimenti tutti gli iscritti diventano irraggiungibili).

1. Vai in DataFirefly Push → Opt-in e Impostazioni.
2. Fai clic su Genera chiavi VAPID. Il modulo crea una coppia di chiavi ECDSA P-256 memorizzata nella configurazione PrestaShop.
3. Inserisci un VAPID subject: un URL mailto: con il tuo indirizzo di contatto tecnico (es. mailto:admin@tuonegozio.com). È l identificatore con cui i push service possono contattarti in caso di abuso.
4. Attiva il modulo tramite l interruttore Notifiche push attivate.

5. Configurazione dell opt-in

La scheda Opt-in e Impostazioni controlla la visualizzazione della richiesta di permesso. Sono disponibili tre stili:

• Campanella: una campanella flottante in basso a destra. L utente fa clic, poi il browser mostra la sua richiesta nativa. La meno invadente.
• Banner: un banner persistente in alto o in basso nella pagina con due pulsanti (consenti / rifiuta).
• Modale: una finestra modale centrata, più visibile ma anche più aggressiva.

Trigger

Per non mostrare la richiesta dal primo secondo (alto tasso di rifiuto), scegli un trigger:

• Ritardo: mostra dopo X secondi (default 15 s)
• Scroll: mostra dopo X % di scroll della pagina (default 40 %)
• Pagine: mostra dopo X pagine viste nella sessione (default 2)

Cooldown

Se il visitatore chiude o rifiuta la richiesta, un cooldown impedisce di riproporla per N giorni (default 7). Evita l effetto “popup molesto” che spinge gli utenti a bloccare definitivamente il dominio.

Limite giornaliero e orari di silenzio

• Max al giorno: numero massimo di notifiche inviate a uno stesso iscritto al giorno (default 3). Oltre, la coda di invio rifiuta silenziosamente i messaggi in eccesso.
• Orari di silenzio: fascia oraria durante la quale nessuna notifica viene consegnata. I messaggi in coda durante questa fascia vengono riprogrammati per il mattino della prima finestra non silenziosa.

6. Cron: configurazione e token

Il cron pilota tutte le operazioni differite: automazioni, coda di invio, svuotamento dei webhook, pulizia. Deve essere chiamato ogni 5 minuti tramite un URL HTTP protetto da token.

Token

Un token univoco viene generato all installazione. Per recuperarlo: DataFirefly Push → Automazioni, il banner blu in alto mostra l URL completo da copiare nel tuo cron.

Esempio di cron Linux

*/5 * * * * curl -s "https://tuonegozio.com/module/dfpushnotifications/cron?token=TUO_TOKEN" > /dev/null

Attività eseguite a ogni tick

1. Reset dei contatori giornalieri (una volta al giorno, al passaggio della mezzanotte)
2. Esecuzione delle automazioni a ritardo maturo (carrelli abbandonati 1 h / 24 h / 72 h, compleanno, inattività, nuovi prodotti, richieste di recensione programmate)
3. Innesco delle campagne programmate la cui data è arrivata
4. Svuotamento della coda di invio (fino a 50 notifiche per batch di default, configurabile)
5. Svuotamento della coda dei webhook (fino a 100 per batch)
6. Pulizia delle voci vecchie (sent > 60 giorni, webhook log > 30 giorni)

La risposta del cron è un JSON che dettaglia ogni passaggio:

{
  "success": true,
  "tasks": {
    "reset_counters": "ok",
    "triggers": { "abandoned_1h": 12, "abandoned_24h": 4, "birthday": 2, "inactivity": 38 },
    "scheduled_campaigns": 1,
    "queue": { "processed": 50, "sent": 47, "failed": 2, "expired": 1 },
    "webhooks": { "processed": 8, "sent": 8, "failed": 0, "dropped": 0 },
    "cleanup": "ok"
  },
  "duration_ms": 1842
}

7. Automazioni: i 9 trigger

Disattivati di default, attivali uno per uno da DataFirefly Push → Automazioni. Ogni card mostra titolo, corpo e statistiche. Fai clic su Modifica per personalizzare il testo e le opzioni.

Variabili disponibili

A seconda del trigger, puoi inserire nel titolo e nel corpo:

• {first_name}: nome del cliente (vuoto per i visitatori anonimi)
• {cart_total}: importo del carrello abbandonato, formattato con la valuta
• {order_reference}: riferimento dell ordine
• {order_total}: importo totale dell ordine
• {product_name}: nome del prodotto (di nuovo disponibile, calo di prezzo)
• {product_price}: prezzo attuale del prodotto
• {products_count}: numero di nuovi prodotti (riepilogo)

Carrello abbandonato (3 solleciti)

Tre trigger indipendenti: abandoned_cart_1h, abandoned_cart_24h, abandoned_cart_72h. Il modulo registra ogni modifica del carrello in ps_dfpush_cart_watch e marca il carrello come convertito non appena un ordine viene validato. Il cron invia ogni sollecito alla maturazione, salvo se il carrello è stato convertito nel frattempo.

Di nuovo disponibile

Sulla scheda prodotto, un pulsante Avvisami quando torna disponibile appare automaticamente quando il prodotto è esaurito. L iscritto fa clic, viene richiesto l opt-in push se necessario, poi il modulo registra un watcher in ps_dfpush_product_watch. Non appena una modifica di stock porta la quantità disponibile sopra 0, il watcher è notificato e marcato come elaborato.

Calo di prezzo

Stesso principio con il pulsante Avvisami se il prezzo cala. Il watcher memorizza il prezzo di riferimento al momento dell opt-in. La notifica viene inviata non appena un aggiornamento prodotto porta il prezzo sotto il 99 % del prezzo di riferimento (una soglia che evita inneschi parassiti per arrotondamenti).

Conferma d ordine

Innescata dall hook actionValidateOrder. Inviata immediatamente, senza rispettare gli orari di silenzio (transazionale). Link diretto alla pagina di dettaglio dell ordine.

Spedizione

Innescata da actionOrderStatusUpdate non appena lo stato passa a uno marcato come shipped in PrestaShop. Link al dettaglio ordine (che contiene il tracking se usi un modulo di tracking).

Richiesta di recensione

Programmata X giorni dopo il passaggio dell ordine a uno stato di consegna (default 7 giorni, configurabile nel JSON config del trigger). La notifica viene messa in coda con uno scheduled_at futuro, il cron la consegna quando arriva il momento.

Compleanno

Il cron legge il campo birthday del cliente PrestaShop e invia la notifica il giorno X all ora configurata. Un deduplicatore evita più invii nello stesso anno.

Inattività

Identifica gli iscritti la cui last_visit risale a più di N giorni (default 30). Per evitare il fastidio, uno stesso iscritto viene notificato al massimo una volta ogni 30 giorni tramite questo trigger.

Nuovi prodotti

Riepilogo giornaliero inviato a un ora configurabile (default 10 h). Il modulo aggrega i prodotti creati nelle ultime 24 ore e invia una notifica che menziona il nome del primo e il totale. Ideale per un negozio che aggiunge regolarmente catalogo.

8. Builder di campagne

Per le operazioni occasionali: DataFirefly Push → Campagne → Nuova campagna. Il modulo è diviso in cinque sezioni.

Contenuto

• Nome campagna: nome interno (mai mostrato agli iscritti)
• Titolo notifica: 80 caratteri max
• Corpo: 250 caratteri max
• URL clic: dove reindirizza il clic
• URL icona: piccolo logo (default il logo del tuo negozio)
• URL immagine grande: immagine hero, 1024 × 512 consigliato (solo Chrome)
• URL badge: PNG monocromatico 72 × 72 (Android)

Pulsanti d azione

Fino a due pulsanti con la loro etichetta e URL. Appaiono sotto la notifica su Chrome desktop e Android. Ideale per offrire più CTA (Vedi l offerta / Ignora).

Pubblico

Vedi la sezione Segmentazione qui sotto.

Programmazione e consegna

• Invia il: data / ora di invio. Vuoto = immediato (al prossimo svuotamento del cron).
• Urgenza: very-low, low, normal, high. Influisce sulla priorità lato push service.
• TTL: tempo di vita in secondi (default 86400 = 24 h). Se il browser dell iscritto è offline più a lungo, la notifica scade.
• Richiedi interazione: notifica persistente fino a clic o chiusura manuale (solo Chrome).

9. Segmentazione

Combinabile con AND logico. Tutti i criteri vuoti = nessuna restrizione.

Criterio	Effetto
Lingue	L iscritto parla almeno una di queste lingue (caselle spuntate)
Paesi	Paese rilevato all iscrizione (basato su lingua / IP / geo)
Dispositivi	mobile / desktop / tablet (rilevato all iscrizione)
Browser	Chrome, Firefox, Safari, Edge, Opera, Samsung Internet
Gruppi clienti	L iscritto è collegato a un cliente PrestaShop in almeno uno dei gruppi
Cronologia d acquisto	Qualsiasi (default), Ha comprato, Non ha mai comprato
Attivo negli ultimi N giorni	Ultima visita meno di N giorni fa (basato su ps_dfpush_customer_activity)

Il pulsante Anteprima dimensione pubblico calcola via AJAX il numero esatto di iscritti corrispondenti. Utile per verificare che il targeting non sia troppo restrittivo prima dell invio.

10. A/B test

Su ogni campagna, il campo % di pubblico per la variante B definisce la quota di pubblico che riceve la variante B (da 0 a 50). La ripartizione è deterministica: per un dato id_subscriber, l iscritto riceve sempre la stessa variante (basato su id_subscriber % 100 < split).

La variante B sovrascrive solo i campi compilati. Puoi ad esempio cambiare solo il titolo, o testare solo un immagine. Le statistiche sono memorizzate separatamente:

• stats_delivered / stats_clicked / stats_revenue: variante A
• stats_b_delivered / stats_b_clicked / stats_b_revenue: variante B

Le colonne appaiono nell elenco delle campagne con un badge A/B accanto al nome.

11. Attribuzione del fatturato

Meccanismo chiave del modulo: collegare gli ordini alle notifiche che li hanno innescati.

Flusso

1. Il modulo invia una notifica con un track_token univoco (32 caratteri hex) nel payload.
2. Il service worker intercetta il clic e reindirizza a /module/dfpushnotifications/track?t=TOKEN&click=1&u=URL.
3. Il controller track deposita un cookie dfpush_attr=TOKEN (30 giorni, SameSite=Lax) e reindirizza all URL finale.
4. Il cliente naviga, aggiunge al carrello, valida l ordine.
5. All hook actionValidateOrder, l AttributionService legge il cookie, trova la notifica in ps_dfpush_notifications, scrive id_order + revenue + currency sulla riga.
6. Il servizio incrementa stats_revenue (o stats_b_revenue a seconda della variante) sulla campagna o sul trigger, attiva il webhook order.attributed, poi cancella il cookie.

Limiti dell attribuzione

• Finestra fissa di 30 giorni. Oltre, l attribuzione non si applica più.
• Un solo cookie per iscritto. Se l utente fa clic su una seconda notifica prima di ordinare, è l ultima ad essere accreditata (modello last click).
• L attribuzione richiede che il clic e l ordine avvengano sullo stesso browser (il cookie è legato al browser).
• Un ordine già attribuito non può essere riattribuito (il campo id_order > 0 blocca la doppia contabilizzazione).

12. Topics

I topics sono canali di iscrizione tematici che i clienti attivano dal proprio account. Esempio: Promozioni, Nuovi prodotti, Avvisi di disponibilità. Un iscritto che spunta solo Promozioni riceverà unicamente le campagne che mirano a quel topic.

Creare un topic

1. DataFirefly Push → Topics → Nuovo topic
2. Codice: identificatore interno senza spazi (es. flash_deals)
3. Ordine di visualizzazione: posizione nella lista mostrata al cliente
4. Attivo: visibile ai clienti
5. Opt-in di default: pre-spuntato al momento dell iscrizione
6. Traduzioni: un nome e una descrizione per lingua installata

Mirare a un topic in una campagna

La segmentazione include un criterio Topics nel resolver. Per attivarlo dall UI: attualmente solo via JSON personalizzato (la casella Topics arriverà in un aggiornamento minore). Gli iscritti senza alcun topic sottoscritto ricevono tutto (retrocompatibilità).

13. Inbox in-app

L endpoint /module/dfpushnotifications/inbox restituisce le 20 notifiche più recenti dell iscritto corrente in JSON. Il frontend apre questa inbox tramite la modale unificata accessibile dall account cliente (tile Notifiche push).

La modale mostra anche lo stato di iscrizione (con pulsante iscriviti / disiscriviti) e l elenco dei topics. Per chiamarla manualmente dal tuo tema:

// Apri la modale
window.dfpush.openManagePopup();

// Verifica lo stato di iscrizione
const isOn = window.dfpush.isSubscribed();

14. Webhook

I webhook inviano gli eventi del modulo a Zapier, Make, n8n o al tuo backend. Ogni webhook è firmato HMAC-SHA256 sul corpo grezzo della richiesta.

Creare un webhook

1. DataFirefly Push → Webhook → Nuovo webhook
2. URL: il tuo endpoint (HTTPS consigliato)
3. Secret: generato automaticamente, copialo lato ricevente
4. Eventi: spunta gli eventi da consegnare tra gli 8 disponibili
5. Fai clic su Invia ping di test per verificare che il tuo endpoint risponda 2xx

Eventi disponibili

• subscriber.subscribed: nuovo opt-in
• subscriber.unsubscribed: disiscrizione
• subscriber.expired: il push service ha restituito 410 Gone
• notification.sent: notifica consegnata con successo
• notification.clicked: clic registrato
• notification.failed: fallimento definitivo dopo 3 tentativi
• campaign.sent: campagna terminata
• order.attributed: ordine collegato a una notifica

Formato del payload

{
  "event": "notification.clicked",
  "timestamp": "2026-05-28T14:32:18+00:00",
  "shop": 1,
  "data": {
    "id_subscriber": 482,
    "id_campaign": 12,
    "id_trigger": 0,
    "id_notification": 9182,
    "track_token": "abc123...",
    "url": "https://tuonegozio.com/promozioni",
    "ab_variant": "A"
  }
}

Header HTTP inviati

• Content-Type: application/json
• X-DfPush-Event: notification.clicked
• X-DfPush-Signature: sha256=<hex>
• X-DfPush-Timestamp: 1748443938
• User-Agent: DataFireflyPush/1.2

Verificare la firma lato ricevente

Esempio PHP:

$body     = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $TUO_SECRET);
$received = explode('=', $_SERVER['HTTP_X_DFPUSH_SIGNATURE'])[1] ?? '';
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
// Firma valida, elaborare il payload
$payload = json_decode($body, true);

Retry e drop

Se il tuo endpoint risponde qualcosa di diverso da 2xx, il modulo ritenta con backoff esponenziale fino a 5 tentativi. Dopo, il log è marcato dropped e l evento è perso. I log sent e dropped sono purgati dopo 30 giorni.

15. Multi-negozio e multilingua

Tutti gli iscritti, campagne, automazioni, topics e webhook sono collegati a un id_shop. In multi-negozio:

• Seleziona il negozio target nel selettore del back-office prima di creare una campagna o un automazione
• Il cron è unico ma filtra automaticamente per negozio
• Le chiavi VAPID sono condivise tra negozi (una sola coppia per tutti)

Lato lingua: il modulo è fornito in IT, EN, FR, ES e DE. La lingua dell iscritto viene rilevata all iscrizione e memorizzata. Puoi segmentare per lingua nelle campagne.

16. GDPR e buone pratiche

• Consenso: l iscrizione si basa sull opt-in nativo del browser, che è una prova di consenso compatibile con il GDPR.
• Dati personali: il modulo memorizza l endpoint Web Push, l IP al momento dell iscrizione, lo user-agent, la lingua e il paese. Nessuna trasmissione a terzi.
• Disiscrizione: un clic sul pulsante Disiscriviti della modale o la disattivazione delle notifiche nel browser mette l iscritto in stato revoked.
• Diritto all oblio: l eliminazione di un account cliente nel BO elimina anche i suoi iscritti collegati.
• Orari di silenzio: di default 22 h – 8 h. Adatta al tuo target (B2B = orario d ufficio, B2C = serata).
• Limite giornaliero: di default 3/giorno. Oltre, tasso di disiscrizione molto elevato.

17. Risoluzione dei problemi

L opt-in non viene mostrato

• Verifica che il tuo sito sia in HTTPS (non HTTP).
• Verifica che le chiavi VAPID siano generate (Impostazioni).
• Verifica che l interruttore Notifiche push attivate sia attivo.
• Apri la console del browser (F12) e cerca errori lato dfpush-frontend.js.
• Se hai già rifiutato o ignorato la richiesta, il cooldown blocca per N giorni. Cancella i cookie del dominio per reimpostare, o cambia browser per testare.

Il cron non si esegue

• Chiama l URL manualmente nel tuo browser: dovresti vedere un JSON con success: true. Se vedi un 403 invalid_token, il token è copiato male.
• Verifica l ultima esecuzione nella dashboard (Dashboard, blocco Sistema).
• Su alcuni host, il timeout cURL dei cron è di 30 s. Se la coda è molto grande, aumenta la frequenza del cron a ogni 1 o 2 minuti per elaborare batch più piccoli.

Le notifiche non partono

• Scheda Coda: se le righe sono in pending, è perché il cron non ha girato dalla loro creazione.
• Se sono in failed, fai clic sulla riga per vedere il codice HTTP e il messaggio di errore del push service.
• 410 Gone = l iscrizione non è più valida (l utente si è disiscritto o ha cancellato il suo browser). Il modulo marca automaticamente l iscritto come expired.
• 429 Too Many Requests = rate limit lato push service. Il modulo ritenta automaticamente con backoff.

Gli ordini non vengono attribuiti

• Verifica che i cookie di terze parti non siano bloccati dal browser del cliente (modalità privata, alcuni anti-tracker).
• Il cookie scade dopo 30 giorni: un ordine effettuato 31 giorni dopo il clic non sarà attribuito.
• Se vedi id_order = 0 in ps_dfpush_notifications mentre l ordine è stato effettuato, verifica che gli hook actionValidateOrder siano correttamente registrati (Moduli → Hook → actionValidateOrder).

Errore SQL con “LIMIT 1 LIMIT 1”

Bug interno corretto in 1.2.0 (Db::getValue e Db::getRow aggiungono automaticamente il proprio LIMIT 1). Se vedi ancora questo errore, verifica di aver installato l ultima versione del modulo.

18. FAQ

Quanti iscritti può gestire il modulo ?

Il modulo non ha limiti codificati. In pratica, il fattore limitante è il tempo di esecuzione del cron: su un hosting condiviso standard, conta circa 50 invii al minuto (limitato dai push service). Per 10 000 iscritti, prevedi un cron ogni 1 o 2 minuti durante l invio di una grande campagna.

Safari iOS è davvero escluso ?

Safari iOS supporta Web Push da iOS 16.4 ma solo per i siti installati come PWA sulla schermata home. Su un Safari classico, l API Notification restituisce undefined. È una limitazione di Apple, non del modulo.

Posso migrare i miei iscritti da OneSignal o Firebase ?

No. Gli endpoint push sono legati alla coppia di chiavi VAPID utilizzata all iscrizione. Se cambi la coppia, le iscrizioni esistenti diventano invalide. Una migrazione richiederebbe una re-iscrizione degli utenti.

Il modulo funziona su PrestaShop 1.7 ?

No, solo PrestaShop 8.0 fino a 9.x. La versione 1.7 utilizza un architettura admin diversa che richiederebbe un fork dedicato.

Posso personalizzare il service worker ?

Sì, il file views/js/sw-template.js è renderizzato dal controller swjs.php e può essere esteso. Attenzione: ogni modifica del service worker richiede un nuovo register() lato client. I visitatori esistenti manterranno la versione precedente finché il browser non rileverà il cambiamento (generalmente 24 h).

Come esportare gli iscritti ?

Scheda Iscritti, pulsante Esporta CSV. Il file contiene endpoint, browser, dispositivo, lingua, paese, data di iscrizione e contatori di invio / clic.

Supporto

Per qualsiasi domanda non coperta da questa guida, contatta il supporto DataFirefly. Per segnalare un bug, allega i dettagli della tua versione PrestaShop, PHP e il contenuto della risposta JSON del cron.