PWA Storefront Pack

Guida completa all’installazione, configurazione e utilizzo di PWA Storefront Pack: il plugin che trasforma il tuo negozio WooCommerce in una Progressive Web App installabile, con modalità offline e notifiche push VAPID native (senza Firebase, senza OneSignal, senza abbonamento mensile).

Panoramica e principio di funzionamento

PWA Storefront Pack aggiunge al tuo WooCommerce tre mattoni indipendenti ma complementari:

• Web App Manifest — i tuoi clienti possono installare il tuo negozio sulla schermata Home come una vera app nativa (icona, splash screen, modalità standalone senza barra degli indirizzi).
• Service Worker — cache intelligente delle pagine e delle risorse, pagina offline personalizzabile, esclusioni automatiche delle zone sensibili (carrello, checkout, il mio account).
• Notifiche push VAPID — implementazione completa del protocollo Web Push in PHP puro: ECDSA P-256, JWT ES256, cifratura aes128gcm. Il tuo server dialoga direttamente con i servizi push dei browser.

Requisiti

• WordPress 6.0 o superiore
• WooCommerce 7.0 o superiore
• PHP 7.4 o superiore con l’estensione openssl (attivata di default su tutti gli hosting)
• HTTPS obbligatorio — i browser rifiutano di registrare un Service Worker o gestire notifiche push su HTTP (tranne localhost in sviluppo)

Installazione

1. Scarica l’archivio pwa-storefront-pack.zip dal tuo account DataFirefly.
2. In WordPress, vai su Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona lo ZIP e clicca su Installa ora, poi Attiva.
4. All’attivazione, il plugin crea tre tabelle SQL (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) e genera automaticamente la tua coppia di chiavi VAPID.
5. Vai su WooCommerce → PWA Storefront per configurare.

Configurazione generale

La scheda General centralizza l’identità della tua app:

• Enable PWA — interruttore principale. Disattiva per rimuovere temporaneamente il manifest e il Service Worker senza disinstallare il plugin.
• App name — nome completo mostrato all’installazione e sullo splash screen (es. «Il Mio Negozio Ufficiale»).
• Short name — etichetta corta sotto l’icona della schermata Home, limitata a 12 caratteri per convenzione Android.
• Theme color — colore della barra degli indirizzi e del selettore attività (consigliato: il tuo colore di brand principale).
• Background color — sfondo dello splash screen durante il caricamento dell’app (di solito bianco o molto chiaro).

URL degli endpoint

Il plugin serve due endpoint critici:

• https://tuo-sito.it/pwasp-manifest.json — il Web App Manifest
• https://tuo-sito.it/pwasp-service-worker.js — il Service Worker

Manifest

La scheda Manifest controlla il comportamento dell’app installata:

• Display mode — standalone di default (consigliato, esperienza tipo app). Altre opzioni: fullscreen, minimal-ui, browser.
• Orientation — any, portrait o landscape. Su mobile, portrait è spesso la più adatta ai negozi.
• Start URL — percorso dove l’app si apre al lancio. Default /. Puoi puntare a /negozio per aprire direttamente il catalogo.
• Scope — ambito di URL controllato dall’app. Solitamente /. Restringilo solo se usi la PWA solo in una sottocartella.
• Categories — indizi per gli app store web (Chrome, Edge). Esempio: shopping,business.
• Shortcuts — attiva per generare scorciatoie Negozio / Carrello / Il mio account accessibili tramite pressione prolungata sull’icona della schermata Home.

Icone dell’applicazione

La scheda Icons permette di associare le tue icone dalla libreria multimediale WordPress. Sono gestiti cinque formati:

• Icon 192×192 (any purpose) — obbligatorio. Usato su Android, nei risultati del motore di ricerca.
• Icon 512×512 (any purpose) — obbligatorio. Icona dello splash screen al lancio.
• Maskable 192×192 — opzionale. Con margine di sicurezza interno del 10 % per le icone adattive Android (forme rotonde, quadrate, a goccia).
• Maskable 512×512 — opzionale. Stesso principio per lo splash screen.
• Apple Touch Icon 180×180 — per iOS. Quadrata, senza angoli arrotondati (iOS li aggiunge automaticamente).

Finché nessuna icona è configurata, il plugin utilizza icone predefinite fornite (branding DataFirefly). Sostituiscile prima di andare in produzione.

Modalità offline e strategia di cache

La scheda Offline & Cache configura il comportamento del Service Worker:

Strategie

• Network first (consigliato) — il browser prova la rete per primo, poi ripiega sulla cache se offline. Massima freschezza di prezzi e scorte.
• Cache first — la cache risponde immediatamente, la rete aggiorna in background. Più veloce ma può mostrare prezzi leggermente obsoleti.

Le strategie si applicano solo alle pagine HTML. Gli altri tipi di risorse hanno strategie fisse ottimali:

• CSS / JS / font → cache-first (cambiano solo con aggiornamenti di versione)
• Immagini prodotto → stale-while-revalidate (visualizzazione immediata dalla cache, refresh in background)

Ambito della cache

Tre caselle permettono di attivare/disattivare la cache per tipo:

• Cache HTML pages — pagine prodotto, categoria, homepage, articoli
• Cache CSS / JS / fonts — lo scheletro del tuo tema
• Cache images — visual di prodotto, immagini degli articoli del blog

Pagina offline

Due opzioni:

• Usare la schermata predefinita — schermata minimalista integrata nel plugin (icona, messaggio, pulsante Riprova), con i colori del tuo brand.
• Usare una pagina personalizzata — seleziona una pagina WordPress esistente. Verrà pre-cachata all’installazione del Service Worker e servita in caso di fallimento di rete.

Banner di installazione

La scheda Install Banner controlla la promozione dell’installazione:

• Delay (page views) — numero di pagine viste prima della visualizzazione. 3 di default: l’utente ha manifestato un interesse minimo senza essere assillato dalla prima visita.
• Banner title / text / CTA / Dismiss — testi totalmente personalizzabili, traducibili via .pot.

Comportamento:

• Su Chrome, Edge, Opera, Samsung Internet: il banner appare quando il browser segnala che il sito è installabile (beforeinstallprompt). Un clic sul CTA mostra la finestra nativa di installazione.
• Su iOS Safari: il banner mostra automaticamente le istruzioni «Tocca Condividi, poi Aggiungi alla schermata Home» (Apple non offre API di installazione programmatica).
• Rifiuto memorizzato 7 giorni — se l’utente chiude il banner, non riappare per una settimana.
• Rilevamento automatico — se l’app è già installata (modalità standalone rilevata), il banner non viene più mostrato.

Notifiche push: le chiavi VAPID

Le notifiche push utilizzano il protocollo VAPID (Voluntary Application Server Identification), standard W3C. All’attivazione del plugin, una coppia di chiavi ECDSA P-256 viene generata automaticamente:

• Chiave pubblica — condivisa con i browser degli iscritti (via JavaScript). 65 byte, codificata base64url.
• Chiave privata — mai trasmessa, serve a firmare ogni invio. 32 byte.

La scheda Push Notifications mostra la tua chiave pubblica in chiaro e il numero di iscrizioni attive. Puoi copiarla per eventuali test esterni.

Rigenerazione delle chiavi

Il pulsante Regenerate keys genera una coppia nuova. Questa operazione è distruttiva:

VAPID subject

Campo VAPID subject: indirizzo di contatto nel formato mailto:tu@esempio.it o https://esempio.it/contatti. Alcuni servizi push (Mozilla in particolare) lo usano per contattarti in caso di abuso rilevato dal tuo server. Precompilato con l’email admin di WordPress.

Opt-in prompt e GDPR

La sezione Opt-in prompt configura la pre-richiesta mostrata prima della finestra di dialogo nativa di permesso:

• Show opt-in prompt — attiva la pre-richiesta personalizzata. Consigliato: la finestra nativa da sola ha un tasso di rifiuto alto e blocca ogni nuova richiesta per 30 giorni.
• GDPR consent required — non mostra mai la finestra nativa senza clic esplicito dell’utente sul tuo CTA. Richiesto in Europa per essere conforme GDPR.
• Delay (seconds) — attesa prima della visualizzazione. 10 secondi di default: lasciare all’utente il tempo di esplorare prima di sollecitare il permesso.
• Prompt title / text / CTA / Dismiss — testi totalmente personalizzabili.

Trigger automatici

Il plugin fornisce tre automazioni collegate direttamente agli hook WooCommerce. Ciascuna è attivabile indipendentemente.

Stato ordine

Hook: woocommerce_order_status_changed.
Il cliente identificato (non gli ospiti) riceve una notifica a ogni transizione di stato del suo ordine. Titolo: «Ordine #1042 aggiornato». Corpo: «Stato: Spedito». Clic → pagina di tracciamento dell’ordine.

La notifica utilizza un tag unico per ordine (order-1042): gli aggiornamenti successivi sostituiscono il precedente invece di accumularsi.

Nuovo ordine (admin)

Hook: woocommerce_new_order.
Tutti gli utenti con ruolo administrator o shop_manager e iscritti alle push ricevono una notifica a ogni nuovo ordine. Titolo: «Nuovo ordine ricevuto». Corpo: «Ordine #1042 — 189,00 €». Clic → schermata di modifica dell’ordine.

L’URL admin è HPOS-aware: se il tuo WooCommerce usa High-Performance Order Storage, il link punta al nuovo schema (admin.php?page=wc-orders). Altrimenti al vecchio (post.php?post=X).

Ritorno in stock

Hook: woocommerce_product_set_stock e woocommerce_variation_set_stock.
Quando un prodotto passa da «esaurito» a «disponibile», il plugin invia una notifica a tutti i visitatori che si erano aggiunti alla sua lista d’attesa. Titolo: «Di nuovo disponibile!». Corpo: «Sneakers pelle premium edizione limitata è di nuovo disponibile». Immagine del prodotto in anteprima se disponibile.

Ogni voce viene marcata notified_at dopo l’invio riuscito, per evitare duplicati se lo stock oscilla.

Compositore broadcast

Menu: WooCommerce → PWA Broadcast. Interfaccia per inviare una notifica manuale a tutti gli iscritti attivi (campagne marketing, annunci, ecc.).

Campi:

• Title — titolo della notifica (100 caratteri max consigliati)
• Message — corpo della notifica (200 caratteri max consigliati)
• Open URL — pagina dove l’utente atterra al clic (di default la homepage)
• Image URL — immagine grande mostrata nella notifica (Android solo, iOS non la mostra)

Un’anteprima in tempo reale mostra la resa approssimativa della notifica sul lato destro dello schermo.

Due pulsanti:

• Send broadcast — invio a tutti gli iscritti attivi (conferma richiesta)
• Send test to me — invio solo alle tue iscrizioni. Utile per validare la resa prima di un broadcast massivo.

Lista d’attesa ritorno in stock (API JavaScript)

Per permettere ai visitatori di iscriversi alla lista d’attesa di un prodotto esaurito, chiama dal tuo tema:

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('Sarai notificato non appena tornerà disponibile!');
    }
  });

Comportamento:

1. Se l’utente non è ancora iscritto alle push, si apre la finestra di dialogo nativa di permesso.
2. Una volta registrata l’iscrizione lato server, la voce viene aggiunta alla lista d’attesa del prodotto.
3. Al ritorno in stock rilevato, una push viene inviata automaticamente.

Puoi chiamare questa API da qualsiasi pulsante personalizzato o via un mu-plugin agganciato a woocommerce_single_product_summary.

Altre API JS esposte

// Iscriversi manualmente (ad esempio da un pulsante personalizzato)
window.PWASP.subscribePush();

// Disiscriversi (pulsante «Annulla iscrizione»)
window.PWASP.unsubscribePush();

API REST

Il plugin espone sei endpoint sotto il namespace pwasp/v1:

• POST /wp-json/pwasp/v1/subscribe — registra un’iscrizione. Body: oggetto PushSubscription del browser.
• POST /wp-json/pwasp/v1/unsubscribe — rimuove un’iscrizione. Body: { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test — invio di test all’utente corrente (auth richiesta, capability manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast — diffusione a tutti gli iscritti (auth richiesta).
• POST /wp-json/pwasp/v1/regenerate-vapid — rigenera le chiavi VAPID (auth richiesta).
• POST /wp-json/pwasp/v1/waitlist — aggiunge a una lista d’attesa. Body: { subscription_id, product_id }.

Autenticazione: nonce WordPress X-WP-Nonce per gli endpoint pubblici, capability manage_woocommerce per gli endpoint admin.

Compatibilità e casi particolari

HPOS (High-Performance Order Storage)

Il plugin dichiara formalmente la sua compatibilità HPOS a WooCommerce via FeaturesUtil::declare_compatibility. Vedrai la casella spuntata in WooCommerce → Impostazioni → Avanzate → Funzionalità.

Plugin di cache

Aggiungi le seguenti esclusioni nel tuo plugin di cache:

• /pwasp-manifest.json
• /pwasp-service-worker.js

Alcuni plugin (WP Rocket, LiteSpeed) offrono anche un’opzione per non cachare i file JavaScript di Service Worker — attivala se disponibile.

iOS e Safari

Supporto per versione:

• iOS 16.4 e successive — installazione via «Aggiungi a schermata Home» e notifiche push (solo per PWA installate)
• iOS 15 e 16.3 — installazione possibile, notifiche push non disponibili
• iOS 14 e inferiori — installazione possibile, nessuna notifica

Su iOS, le push funzionano solo se l’utente ha prima installato la PWA sulla sua schermata Home. È un vincolo di Apple, non del plugin.

Sottocartelle e multisite

Il plugin funziona su WordPress installato nella radice (esempio.it) o in una sottocartella (esempio.it/negozio/). Gli endpoint sono risolti dinamicamente via home_url(). In multisite, attiva il plugin per ogni sito — ogni sito avrà la propria coppia di chiavi VAPID e la propria base di iscritti.

Risoluzione dei problemi

«Il Service Worker non è registrato»

1. Verifica che il tuo sito sia effettivamente in HTTPS (https:// e non http://).
2. Apri la console del browser (F12 → scheda Application → Service Workers). C’è un messaggio di errore?
3. Prova l’URL https://tuo-sito.it/pwasp-service-worker.js in una scheda. Il file deve restituire JavaScript, non una pagina 404 né la home di WordPress.
4. Se è 404: vai su Impostazioni → Permalink e clicca su Salva modifiche per aggiornare le regole di rewrite.

«Le notifiche non arrivano»

1. Verifica in WooCommerce → PWA Subscribers che la tua iscrizione sia elencata e in stato active.
2. Usa il pulsante Send test to me nel compositore broadcast. Ricevi la notifica?
3. Se no: la finestra di permesso potrebbe essere stata rifiutata. Su Chrome: apri il lucchetto nella barra degli indirizzi → Notifiche → Consenti.
4. Su Windows/macOS: verifica che Chrome/Firefox non sia in modalità «Non disturbare».

«La rigenerazione delle chiavi VAPID è fallita»

Causa probabile: l’estensione PHP openssl non è disponibile sul tuo hosting, o la generazione di chiavi ECDSA è bloccata. Verifica tramite un file phpinfo.php che la sezione openssl sia presente e che la curva prime256v1 sia supportata. Contatta il tuo hosting se necessario.

Disinstallazione

Rimozione via Plugin → Plugin installati → Elimina:

• Le tre tabelle SQL vengono eliminate
• Le opzioni del plugin vengono rimosse
• I task cron programmati vengono annullati
• Le icone caricate nella libreria multimediale restano (possono essere usate altrove)

Supporto

Per qualsiasi domanda o anomalia, apri un ticket dal tuo account DataFirefly. Risposta entro 24 h lavorative.