DfPwaPush — Guida completa

DfPwaPush combina due funzioni in un unico plugin Shopware: trasforma il tuo storefront in una Progressive Web App installabile (manifest, service worker, pagina offline, banner di installazione) e ti consente di riattivare i tuoi clienti con notifiche Web Push completamente self-hosted. Nessun servizio di terze parti (niente Firebase, niente OneSignal), nessuna dipendenza Composer: la cifratura Web Push (RFC 8291) e la firma VAPID (RFC 8292) sono implementate in modo nativo con le estensioni OpenSSL e cURL già richieste da Shopware. Tutti i dati di iscrizione restano sul tuo server. Questa guida copre l’installazione, la configurazione PWA e Push, la generazione delle chiavi VAPID, la creazione e l’invio di campagne, l’esecuzione in background e la risoluzione dei problemi.

Installazione

1. Scarica l’archivio DfPwaPush-1.0.2.zip dal tuo account DataFirefly.
2. Installalo tramite Amministrazione → Estensioni → Le mie estensioni → Carica estensione, oppure copia la cartella decompressa DfPwaPush in custom/plugins/.
3. Esegui l’installazione e l’attivazione:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfPwaPush
   bin/console cache:clear

4. All’installazione, il plugin crea le sue due tabelle (df_push_subscription e df_push_campaign) e registra la sua ScheduledTask di invio.

Requisito HTTPS

I service worker e l’API Web Push esistono solo su un’origine sicura. Il tuo negozio deve essere servito su HTTPS (solo localhost è un’eccezione in sviluppo). Su un negozio in HTTP, il plugin resta silenzioso sul front e lo registra nella console del browser.

Dove trovare il plugin nell’amministrazione

Dopo l’attivazione, una voce Campagne push appare nel menu Marketing dell’amministrazione. È lì che crei, pianifichi e monitori le tue campagne. Tutta la configurazione PWA e Push avviene nella configurazione del plugin, per canale di vendita, tramite Estensioni → Le mie estensioni → DfPwaPush → ⋯ → Configura.

Generazione delle chiavi VAPID

Il Web Push si basa su una coppia di chiavi VAPID (standard RFC 8292) che autentica il tuo server presso i servizi push dei browser. Generale con un comando:

bin/console df:pwa-push:vapid:generate

Le chiavi vengono scritte direttamente nella configurazione del plugin. Usa l’opzione --force per rigenerarle. Puoi anche incollare chiavi VAPID esistenti nei campi di configurazione.

Configurazione PWA

La scheda PWA della configurazione (regolabile per canale di vendita) governa l’installabilità del tuo negozio:

• Abilita la PWA: serve il manifest e il service worker.
• Nome e nome breve dell’app: mostrati sulla schermata Home una volta installata.
• Colore del tema / colore di sfondo: per impostazione predefinita #0f172a per il tema.
• Modalità di visualizzazione: standalone, minimal-ui, fullscreen o browser.
• Icone 192 px e 512 px: caricamenti PNG, indispensabili per l’installabilità.
• Banner di installazione: attiva l’invito «Aggiungi alla schermata Home».

Configurazione Push

La scheda Push controlla le notifiche:

• Abilita il Web Push: attiva il banner di opt-in e gli endpoint di iscrizione. Abilitato per impostazione predefinita.
• Chiave pubblica / chiave privata VAPID: generate dal comando precedente.
• Soggetto VAPID: un indirizzo mailto: o l’URL del tuo sito.
• Ritardo di opt-in: numero di secondi prima che appaia il banner di autorizzazione (8 per impostazione predefinita).

Il service worker e gli endpoint dello storefront

Tutte le risorse PWA vengono servite dinamicamente da un controller, il che le rende immuni al passaggio da webpack a Vite nella 6.7:

• GET /df-pwa/manifest.json — il manifest PWA, generato per canale di vendita.
• GET /df-pwa/sw.js — il service worker (header Service-Worker-Allowed: / per controllare l’intera origine).
• GET /df-pwa/icon/{192|512} — le icone PWA.
• GET /df-pwa/offline — la pagina di fallback offline, memorizzata nella cache dal service worker.
• POST /df-pwa/subscribe e POST /df-pwa/unsubscribe — registrazione e rimozione di un’iscrizione (XHR).

Il service worker memorizza nella cache la pagina offline all’installazione, serve un fallback per le navigazioni fallite e mostra le notifiche ricevute tramite l’evento push con reindirizzamento al clic verso l’URL della campagna.

Creare e inviare una campagna

1. Vai su Marketing → Campagne push → Crea una campagna.
2. Compila il titolo, il messaggio e, facoltativamente, un URL di destinazione e un’icona.
3. Limita la campagna a un canale di vendita se necessario (altrimenti vengono presi di mira tutti gli iscritti).
4. Oppure imposti una data di pianificazione e salvi, oppure fai clic su Invia ora.

«Invia ora» mette la campagna in coda immediata (stato scheduled con una data di invio al momento presente); l’attività pianificata la prende in carico nei minuti successivi. Una campagna attraversa gli stati draft → scheduled → sending → sent (o failed), e la scheda mostra i contatori di invii riusciti e falliti.

Invio in background: ScheduledTask e CLI

L’invio delle campagne è gestito dalla ScheduledTask df_pwa_push.send_campaigns, eseguita ogni 300 secondi. Recupera le campagne pianificate in scadenza e le invia a lotti. Puoi anche avviare l’invio manualmente:

bin/console df:pwa-push:send

Web Push nativo, nessuna dipendenza

DfPwaPush implementa l’intero stack Web Push in PHP puro, senza alcuna libreria esterna:

• VAPID / ES256 (RFC 8292): generazione di chiavi P-256 tramite OpenSSL e firma JWT ES256 per autenticare il server.
• Cifratura aes128gcm (RFC 8291): ECDH effimero, derivazione HKDF e cifratura AES-128-GCM del messaggio per ciascun iscritto.
• Invio parallelo tramite curl_multi a lotti, con gestione dei codici di ritorno dei servizi push.

L’implementazione è validata byte per byte rispetto al vettore di test ufficiale dell’RFC 8291, il che garantisce l’interoperabilità con Chrome, Firefox, Edge e Safari.

Pulizia automatica delle iscrizioni

Quando un servizio push risponde che un’iscrizione non esiste più (codici HTTP 404 o 410), l’iscrizione corrispondente viene disattivata automaticamente. Anche le iscrizioni che falliscono ripetutamente (5 fallimenti consecutivi) vengono disattivate. La tua base di iscritti resta pulita senza interventi.

Compatibilità iOS e Safari

FAQ e risoluzione dei problemi

L’installazione da ZIP fallisce con «pacchetto minishlink/web-push mancante». Questo errore riguardava le versioni precedenti. Dalla 1.0.1, il Web Push è nativo e il plugin non ha più alcuna dipendenza Composer: la versione attuale si installa su qualsiasi hosting, incluso quello condiviso.

Non appare nulla per creare campagne nel back office. Il modulo di amministrazione è precompilato dalla 1.0.1. Dopo un aggiornamento, esegui bin/console assets:install && bin/console cache:clear e ricarica l’amministrazione forzando la cache (Ctrl+Shift+R). La voce si trova in Marketing → Campagne push.

L’URL /df-pwa/manifest.json restituisce un errore 500. Corretto nella 1.0.2: il metodo setTwig() del controller padre è stato rimosso in Shopware 6.7, il che faceva fallire tutte le rotte /df-pwa/*. Aggiorna alla 1.0.2 o successiva.

Non succede nulla sullo storefront. Apri la console del browser: il plugin registra ogni decisione con il prefisso [DfPwaPush] (service worker registrato o meno, chiave VAPID mancante, permesso negato, iOS senza PWA installata…). Verifica anche che il negozio sia in HTTPS.

Il banner di installazione PWA non appare. Chrome emette l’evento beforeinstallprompt solo se il sito è installabile, il che richiede le icone 192 px e 512 px impostate nella configurazione e un service worker attivo. Niente icone, niente banner.

Il banner di notifiche non appare. Verifica che le chiavi VAPID siano generate, che il Web Push sia abilitato e che l’utente non abbia già negato le notifiche. La console mostrerà la ragione esatta.

Cosa succede alla disinstallazione? Con l’opzione di rimozione dei dati, le tabelle df_push_subscription e df_push_campaign vengono eliminate. Senza questa opzione, vengono conservate per preservare i tuoi iscritti e la cronologia delle campagne.