DataFirefly Push — Guida completa

Presentazione e prerequisiti

DataFirefly Push trasforma il tuo negozio WooCommerce in una piattaforma di notifiche Web Push nativa. Senza SDK, senza tracciamento di terze parti: tutta la crittografia (VAPID e cifratura RFC 8291) viene eseguita sul tuo server in PHP puro tramite OpenSSL. Il plugin copre un opt-in intelligente multi-stile, dieci trigger automatici, campagne manuali con builder visuale e segmentazione, una dashboard di analytics completa, una pagina Il mio account dedicata per i tuoi clienti e una conformità GDPR nativa.

• WordPress 6.2 e superiore.
• WooCommerce 7.0 e superiore, testato fino a 9.6, compatibile con HPOS e Cart/Checkout Blocks.
• PHP 8.1 e superiore.
• Multilingue (FR/EN/ES/DE/IT), compatibile con Polylang e WPML.
• Compatibile con LiteSpeed Cache, WP Rocket e altri plugin di cache: il Service Worker viene servito come PHP standalone.

Installazione

1. Scarica l’archivio df-push.zip dal tuo account cliente.
2. Nell’admin di WordPress, vai a Plugin > Aggiungi nuovo > Carica plugin e rilascia l’archivio.
3. Clicca su Attiva.
4. Il menu DF Push appare nella barra laterale di amministrazione con sette sottomenu: Dashboard, Campagne, Iscritti, Trigger, Opt-in, Impostazioni, Webhook e API.

All’attivazione, il plugin crea otto tabelle dedicate con prefisso dfpush_, genera le chiavi VAPID, pianifica il cron giornaliero df_push_daily_lifecycle e registra l’endpoint Il mio account. Non è richiesto alcun intervento manuale.

Prima configurazione: chiavi VAPID e opt-in

Una volta attivato, il plugin è immediatamente funzionale con le impostazioni predefinite: la campanella fluttuante appare in basso a destra dopo cinque secondi, il pre-prompt è attivato, i trigger automatici sono pronti. Verifica semplicemente due cose in DF Push > Impostazioni prima di comunicare sul servizio:

• Chiave pubblica VAPID: il blocco mostra la tua chiave pubblica generata automaticamente (l’application server key utilizzata dal browser). Puoi rigenerarla ma questo invaliderà tutte le iscrizioni esistenti.
• Manifest PWA e icona predefinita: aggiungi la tua icona (minimo 192×192) se site_icon non è definito sul sito.

Scheda Opt-in — prompt, stili e trigger

Questa scheda pilota la richiesta di iscrizione. Cinque stili disponibili, ciascuno posizionabile e tematizzabile:

• Campanella fluttuante (predefinito): pillola discreta in basso a destra o in basso a sinistra.
• Banner in alto o in basso sulla pagina.
• Modale centrato con overlay.
• Slide-in laterale.
• Barra fissa ancorata in alto.

Il pre-prompt soft-ask (raccomandato) mostra il tuo messaggio personalizzato prima della richiesta nativa del browser. Questo meccanismo preserva la tua quota di opt-in: su Chrome, rifiutare il pre-prompt non consuma il budget delle richieste native (×3 contro 1 senza pre-prompt).

Cinque trigger configurabili e combinabili:

• Ritardo (in secondi) dopo il caricamento della pagina.
• Scroll in percentuale della pagina (0 = disattivato).
• Exit-intent al movimento di uscita del mouse (solo desktop).
• X pagine viste nella sessione.
• Aggiunta al carrello (cattura l’evento WooCommerce added_to_cart).

Attiva il test A/B del prompt con un titolo e un messaggio variante B, e una ripartizione configurabile. L’assegnazione viene persistita in localStorage per garantire la coerenza tra sessioni per visitatore.

Scheda Trigger — gli automatismi

Dieci trigger automatici, tutti attivabili individualmente dalla scheda Trigger. Ciascuno si appoggia ad Action Scheduler per gli invii differiti, con un fallback sincrono se Action Scheduler non è disponibile.

Carrello abbandonato

Tre promemoria configurabili, per impostazione predefinita a 1 ora, 24 ore e 72 ore dopo l’abbandono. Il rilevamento cattura l’evento added_to_cart per gli utenti iscritti al Push e pianifica tre azioni df_push_abandoned_cart a intervalli decrescenti. I promemoria vengono annullati automaticamente se l’ordine viene effettuato nel frattempo.

Di nuovo disponibile (back-in-stock)

Sulla pagina del prodotto, i tuoi visitatori iscritti possono unirsi a una lista d’attesa per prodotto. Quando WooCommerce attiva woocommerce_product_set_stock_status con un ritorno a instock, il plugin invia una notifica alla lista d’attesa del prodotto, poi la svuota.

Calo di prezzo

Il plugin mantiene un meta _df_push_last_price per prodotto. A ogni aggiornamento di prodotto, confronta il vecchio e il nuovo prezzo. Se il calo supera la soglia minima in percentuale configurata, viene inviata una notifica all’argomento Promozioni.

Conferma, spedizione, recensione

• Conferma ordine: invio immediato su woocommerce_thankyou all’iscritto se l’ID utente corrisponde.
• Spedizione: rileva il numero di tracciamento sull’ordine leggendo in ordine i meta _tracking_number, _wc_shipment_tracking_items (WooCommerce Shipment Tracking) e _aftership_tracking_number (AfterShip). Se viene trovato un numero, la notifica lo include nel suo messaggio.
• Richiesta di recensione: pianificata X giorni dopo il passaggio dell’ordine allo stato completed (ritardo configurabile).

Compleanno, riattivazione, nuovo prodotto

• Compleanno: il cron giornaliero df_push_daily_lifecycle legge il campo billing_birthday di WooCommerce e invia una notifica agli iscritti il cui compleanno è oggi.
• Riattivazione: invio agli iscritti inattivi da 30, 60 e 90 giorni (finestre configurabili come CSV: 30,60,90).
• Nuovo prodotto: alla pubblicazione di un prodotto, viene inviata una notifica all’argomento Novità.

Scheda Campagne — builder visuale, segmentazione, test A/B

Costruisci una campagna manuale in DF Push > Campagne > Nuova campagna. Il builder offre un’anteprima live della notifica così come apparirà sul dispositivo dell’iscritto.

• Contenuto: titolo, messaggio, URL di destinazione, immagine hero, fino a due pulsanti di azione con etichetta e URL propri.
• Notifica persistente (opzione requireInteraction): la notifica rimane visibile fino all’interazione.
• Segmentazione per lingua, paese, dispositivo, argomento e per comportamento RFM: ordini minimi, carrello medio minimo, giorni di inattività, categoria acquistata. I segmenti comportamentali sono calcolati tramite wc_get_orders al lancio.
• Test A/B: attiva una variante B (titolo e messaggio), la ripartizione è configurabile in percentuale. L’assegnazione è casuale per iscritto, deterministica per ID per la coerenza degli analytics.
• Pianificazione: scegli la data e l’ora, o invia immediatamente.
• Modalità test: invia la campagna solo agli amministratori, dal builder, prima del lancio in produzione.

Il motore di invio frammenta automaticamente il segmento, rispetta le ore di silenzio per fuso orario dell’iscritto, applica il limite di frequenza configurato e purga al volo gli endpoint che restituiscono 404 o 410 (cancellazione lato browser).

Dashboard e analytics

La dashboard DF Push > Dashboard aggrega i tuoi KPI su 30 giorni. Chart.js è bundle locale (nessuna dipendenza CDN esterna).

• KPI: iscritti attivi, tasso di opt-in, invii, tasso di clic (CTR), conversioni, ricavi attribuiti.
• Serie temporale 30 giorni: invii contro clic, una linea al giorno.
• Mappa di calore 7 × 24: migliori fasce orarie di invio in base ai clic, incrociando giorno della settimana e ora del giorno.
• Funnel per campagna: inviata > consegnata > cliccata > convertita.
• Ricavi attribuiti: una finestra di attribuzione configurabile (72 ore per impostazione predefinita) collega ogni clic al primo acquisto effettuato nella finestra da quell’iscritto.
• Esportazione CSV di tutti gli eventi per audit GDPR o integrazione BI.

Pagina cliente: Il mio account → Notifiche

Una pagina dedicata Il mio account → Notifiche viene aggiunta automaticamente alla dashboard di WooCommerce. Il cliente dispone di quattro blocchi:

• Questo dispositivo: stato corrente (attivato, disattivato, bloccato dal browser, non supportato), con pulsante Attiva o Disattiva su questo dispositivo.
• Tutti i tuoi dispositivi: elenco dei dispositivi iscritti (tipo, browser, lingua, ultima attività), con cancellazione individuale o cancellazione totale con un clic.
• Le mie preferenze: caselle per gli argomenti nativi (Novità, Promozioni, Di nuovo disponibile). Salvataggio tramite REST con conferma.
• Cronologia notifiche: le ultime 30 notifiche ricevute, con titolo, corpo, icona, link e data.

L’URL è /il-mio-account/df-push-notifications/ in italiano. Il rewrite endpoint è registrato con il mask EP_ROOT | EP_PAGES, con un’auto-riparazione su init:999 che rileva una regola mancante (caso di flush dei permalink concorrente) e riflusha automaticamente.

GDPR e registro di consenso

La conformità GDPR è trattata in modo nativo, non come un’aggiunta cosmetica. Ogni opt-in e ogni cancellazione viene inscritto nella tabella dfpush_consent_log con:

• ID dell’iscritto.
• Azione: subscribe o unsubscribe.
• IP hashato in SHA-256 (l’IP in chiaro non viene mai persistito).
• User-agent.
• Marca temporale UTC.

Gli Esportatori e Cancellatori di privacy nativi di WordPress sono collegati: un cliente può richiedere l’esportazione o la cancellazione dei suoi dati personali da Strumenti → Esporta dati personali o Strumenti → Cancella dati personali. Il plugin include quindi le sue iscrizioni, i suoi argomenti, la sua inbox e il suo registro di consenso nella risposta — o li elimina secondo la richiesta.

Scheda Impostazioni — anti-spam e attribuzione

Questa scheda centralizza i parametri di rispetto degli iscritti e la finestra di attribuzione:

• Ore di silenzio (quiet hours): intervallo durante il quale non viene inviata nessuna notifica. Sensibile al fuso orario dell’iscritto (letto sul suo dispositivo al momento dell’opt-in tramite Intl.DateTimeFormat().resolvedOptions().timeZone). Per impostazione predefinita 22h-8h locali.
• Limite di frequenza: numero massimo di notifiche al giorno per iscritto. 0 = illimitato.
• Orario di invio intelligente: ottimizza l’orario di invio per iscritto in base alle sue fasce di clic storiche.
• Finestra di attribuzione: durata in ore tra un clic e un ordine perché l’ordine venga attribuito alla notifica. Per impostazione predefinita 72 ore.
• Inbox in-site: attiva o disattiva la campanella fluttuante con la cronologia delle notifiche lato front.
• Manifest PWA: attiva la generazione del manifest per rendere il sito installabile su mobile.

Scheda Webhook e API REST

La scheda Webhook e API copre due meccanismi di integrazione.

Webhook in uscita

Configura uno o più endpoint HTTP per evento. Sono disponibili tre formati:

• Slack: payload { text } compatibile con gli Incoming Webhook di Slack.
• Discord: payload { content } compatibile con i Webhook di Discord.
• Generic: payload JSON completo con event, timestamp, data — compatibile con Zapier, n8n, Make.

Gli eventi disponibili: subscriber.created, campaign.launched, notification.clicked, order.attributed. Le richieste sono non bloccanti (wp_remote_post con blocking=false) per non rallentare mai l’invio principale.

API REST

Sotto il namespace df-push/v1, il plugin espone una route pubblica di invio con token: POST /wp-json/df-push/v1/send con l’header X-DF-Push-Token. Il token è rigenerabile con un clic dall’admin.

curl -X POST https://il-tuo-sito.com/wp-json/df-push/v1/send 
  -H "Content-Type: application/json" 
  -H "X-DF-Push-Token: IL_TUO_TOKEN" 
  -d '{
    "title": "Promo flash",
    "body": "20 % su tutto il catalogo fino a mezzanotte",
    "url": "https://il-tuo-sito.com/promozioni",
    "segment": { "lang": "it", "topic": "promos" }
  }'

Inbox in-site, PWA e multilingue

Tre funzioni complementari coprono i casi in cui l’utente non ha autorizzato il Push.

• Inbox in-site: una campanella fluttuante (configurabile lato front) apre un elenco delle ultime notifiche ricevute dall’utente, lette o meno, anche se non ha mai autorizzato il Push. Particolarmente utile per iOS Safari prima di 16.4 e per gli utenti PWA.
• Manifest PWA: generato dinamicamente in /df-push-manifest.json da site_icon o da un’icona personalizzata. Filtro df_push_manifest disponibile per regolare theme color, display, scope, start_url.
• Multilingue: compatibile con Polylang e WPML. Le notifiche vengono inviate nella lingua dell’iscritto (rilevata all’opt-in), con fallback sulla lingua predefinita del sito. I file .po e .mo in FR, EN, ES, DE, IT sono inclusi.

Service Worker e architettura tecnica

Il Service Worker viene servito da un file PHP standalone all’URL /wp-content/plugins/df-push/sw.php. Questo approccio aggira completamente il routing di WordPress: nessuna possibilità di interferenza con un plugin di cache, un canonical redirect o un altro handler template_redirect.

L’header Service-Worker-Allowed: / viene inviato in risposta per consentire la registrazione con scope radice (scope: '/'), anche se lo script vive sotto /wp-content/.

Lato database, otto tabelle con prefisso dfpush_:

• dfpush_subscribers: iscritti e loro endpoint Push.
• dfpush_topic_subs: assegnazioni argomento ↔ iscritto.
• dfpush_campaigns: campagne manuali con payload, segmento e pianificazione.
• dfpush_notifications: registro delle notifiche individuali inviate.
• dfpush_events: eventi grezzi (opt-in, sent, delivered, clicked, converted) per gli analytics.
• dfpush_inbox: copia persistente delle notifiche per l’inbox in-site.
• dfpush_stock_waitlist: liste d’attesa di ritorno in stock.
• dfpush_consent_log: registro GDPR.

La disinstallazione (eliminazione completa da Plugin) fa drop di queste otto tabelle e purga tutte le opzioni. La semplice disattivazione, invece, conserva i dati per una riattivazione successiva.

Hook per sviluppatori

Il plugin espone azioni e filtri nei punti chiave per estendere il suo comportamento senza modificare il core.

• df_push_booted (azione): attivata dopo il boot del plugin, utile per registrare estensioni personalizzate.
• df_push_payload_build (filtro): modificare il payload JSON inviato al servizio push prima della cifratura.
• df_push_should_send (filtro): cortocircuitare l’invio su condizioni personalizzate (restituire false per saltare).
• df_push_segment_query (filtro): arricchire i criteri di segmentazione comportamentale.
• df_push_webhook_payload (filtro): regolare i payload dei webhook in uscita.
• df_push_manifest (filtro): modificare il manifest PWA generato.
• Azioni Action Scheduler registrate: df_push_send_one, df_push_fan_out, df_push_abandoned_cart, df_push_review_request, df_push_dispatch_campaign.

FAQ e risoluzione dei problemi

Il prompt di opt-in non appare

Tre cause possibili: il permesso del browser è già negato (verifica nelle impostazioni del browser), il permesso è già concesso (il prompt non ha più senso) o un trigger non è stato raggiunto (ritardo non trascorso, scroll insufficiente). Nella console JavaScript, esegui window.DFPush.isSubscribed() per verificare lo stato corrente.

L’admin Iscritti è vuoto anche se un opt-in è riuscito

Verifica nella console di rete che la richiesta POST /wp-json/df-push/v1/subscribe restituisca un codice 200. A partire dalla versione 1.0.1, il plugin re-sincronizza automaticamente qualsiasi PushSubscription esistente con il server a ogni caricamento di pagina, e registra ogni errore di inserimento DB in error_log.

Il Service Worker restituisce un errore di registrazione

Se l’errore del browser è “The script resource is behind a redirect” o “Unexpected token ‘<‘”, testa direttamente l’URL https://il-tuo-sito.com/wp-content/plugins/df-push/sw.php. Devi vedere il codice JavaScript del Service Worker con un Content-Type: application/javascript e l’header Service-Worker-Allowed: /. Se vedi un HTML 403, verifica le regole htaccess che potrebbero bloccare l’esecuzione diretta di file PHP sotto wp-content/plugins/.

Le notifiche non vengono ricevute su iOS

Safari su iOS supporta le notifiche Push solo dalla versione 16.4 e unicamente per i siti installati come PWA tramite il pulsante Aggiungi alla schermata Home. Il manifest PWA generato dal plugin facilita questa installazione. Se non miri specificamente a iOS, non è un problema: gli altri browser ricevono le notifiche normalmente.

Come migrare da OneSignal o Pusher

Gli iscritti esistenti su questi servizi di terze parti non sono portabili: la crittografia Push lega ogni iscrizione a una coppia unica (chiave VAPID del server, endpoint del browser). I tuoi visitatori dovranno re-iscriversi dopo il tuo passaggio a DataFirefly Push. Puoi preparare la transizione disattivando il vecchio SDK alcuni giorni prima e comunicando tramite un banner di pre-annuncio sulla nuova esperienza.

Cosa succede alla disinstallazione?

La semplice disattivazione conserva tutte le tabelle e le opzioni: puoi riattivare il plugin e riprendere da dove avevi lasciato. L’eliminazione completa da Plugin esegue uninstall.php che fa drop delle otto tabelle dfpush_, purga tutte le opzioni del plugin (incluse le chiavi VAPID e il token API) e annulla la pianificazione dei cron. I permalink vengono riflushati automaticamente alla prossima richiesta.