# 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…

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

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

Nessun servizio di terze parti da collegare, nessuna libreria Composer da mantenere. Le chiavi VAPID vengono generate automaticamente all'attivazione, le iscrizioni e gli eventi restano nel tuo database.

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

Nessun servizio esterno da registrare, nessun account sviluppatore Firebase / OneSignal da creare. Le chiavi VAPID che il plugin genera sono sufficienti: autenticano il tuo server applicativo presso i servizi push FCM, Mozilla Push e WNS.

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

Una volta rifiutato il permesso del browser, non può essere richiesto di nuovo via script. Cura il tuo pre-prompt e non concatenare una richiesta al primo scroll: questo schema mostra il 70 % di rifiuto contro il 20-30 % con un pre-prompt attivato al momento giusto.

## 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à_.

Ogni trigger accetta un payload templatizzato: `{firstname}`, `{product_name}`, `{product_price}`, `{old_price}`, `{order_number}`, `{tracking_number}`, `{category}`, `{discount_code}`. Le variabili sono risolte al momento dell'invio, non alla pianificazione.

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

Le azioni cliente (cancellazione, preferenze) passano attraverso le route REST sotto `df-push/v1/account/*`, autenticate da cookie + nonce `wp_rest`. Nessuna azione può essere eseguita su un altro account, anche in caso di manipolazione dell'identificatore del dispositivo nella richiesta.

## 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" }
  }'
```

Conserva questo token come una password. Chiunque lo possieda può inviare notifiche ai tuoi iscritti. Rigeneralo immediatamente se sospetti una compromissione.

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