PWA con notifiche push:
architettura e istruzioni

1Il vincolo che decide tutto

Va letto prima di qualunque riga di codice, perché riscrive il progetto.

Su iOS il Web Push funziona solo dentro una web app aggiunta alla schermata Home, da iOS 16.4 in poi. Mai in Safari. Su Android funziona anche nel browser.

Da questo discendono tre conseguenze che non si aggirano:

• serve HTTPS con certificato valido — un autofirmato non basta, su iOS impedisce anche l'installazione;
• su iOS il pulsante «attiva notifiche» va spento finché l'app non è installata, altrimenti l'utente tocca e non succede niente — e impara che l'app è rotta;
• Notification.requestPermission() deve partire da un gesto dell'utente: un await che lo preceda rompe il legame col tocco e su iOS la richiesta viene ignorata in silenzio.

Cosa non si può fare, e non si potrà a breve

2I cinque requisiti

Se ne manca uno solo, non arriva niente — e senza errori.

3L'architettura

Nessun servizio terzo, nessun SDK, tre dipendenze in tutto.

I pezzi, e perché sono lì

Le dipendenze

Tre: express, web-push e fast-xml-parser (per i feed RSS: un parser fatto di espressioni regolari sarebbe stato una scorciatoia fragile). Nessun Firebase, nessun SDK, nessun account terzo. Le icone sono generate da uno script che scrive i PNG a mano con zlib — sul server non c'erano né ImageMagick né PIL, e aggiungere una libreria di immagini per disegnare una campanella sarebbe stato sproporzionato.

4Il sito notizie multiutente

La fase 3: notizie vere, utenti veri, e ognuno sceglie cosa ricevere e quanto spesso.

«Nuova» vuol dire vista per la prima volta da questo server, non la data del feed: le date dei feed sono inaffidabili, il momento in cui l'abbiamo vista noi è un fatto.

La griglia

Ogni utente sceglie, per ogni categoria — politica, mercati finanziari, sport, guerre e macroeconomia — una frequenza fra: no, 5 minuti, ogni ora, ogni giorno, ogni settimana. Tre regole la rendono sopportabile:

• La frequenza è un massimo. Se nell'intervallo non è uscito niente, non parte niente: una notifica vuota insegna a ignorarle tutte.
• Una notifica per giro. Le categorie che scadono insieme partono in un solo messaggio («4 notizie per te», una riga per categoria). Con tutto a 5 minuti, altrimenti, sarebbero quattro notifiche ogni cinque minuti.
• Cambiare frequenza riparte da adesso. Passare da «settimana» a «5 minuti» non scarica una settimana di arretrati.

Utenti e accesso

5Il ciclo di una notifica

Dove si rompe, e chi se ne accorge.

6Il codice che conta

Il minimo indispensabile, con i commenti che spiegano perché non si può togliere niente.

Il manifest

manifest.webmanifest

{
  "id": "/",
  "name": "Nome completo",
  "short_name": "Nome",
  "start_url": "/?fonte=pwa",
  "scope": "/",
  // standalone o fullscreen: con "browser" iOS non la installa come web app
  "display": "standalone",
  "background_color": "#1e3a8a",
  "theme_color": "#1e3a8a",
  // 192 e 512 sono il minimo per l'installabilita'; maskable evita che
  // Android incornici l'icona in un quadrato bianco
  "icons": [
    { "src": "/icone/192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "/icone/512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "/icone/512m.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ],
  // i link dentro lo scope vanno all'app installata (dove la piattaforma lo permette)
  "handle_links": "preferred",
  "launch_handler": { "client_mode": "navigate-existing" }
}

Il gestore push — il pezzo più delicato

sw.js

self.addEventListener('push', (event) => {
  let dati = {};
  try {
    // event.data e' null se il push arriva senza payload: succede, ed e'
    // uno dei casi in cui la notifica va mostrata lo stesso.
    dati = event.data ? event.data.json() : {};
  } catch (e) {
    try { dati = { testo: event.data.text() }; } catch (e2) { dati = {}; }
  }

  // waitUntil e' OBBLIGATORIO: senza, il browser puo' terminare il service
  // worker prima che showNotification() abbia finito, e la notifica sparisce.
  event.waitUntil(
    self.registration.showNotification(dati.titolo || 'Notifica', {
      body: dati.testo || 'Notifica ricevuta.',
      icon: '/icone/192.png',
      badge: '/icone/192.png',
      tag: 'prova', renotify: true,
      data: { url: dati.url || '/' },
    })
  );
});

Iscrizione, lato pagina

app.js

// La chiave VAPID viaggia in base64url (- e _ al posto di + e /, senza =);
// subscribe() vuole un Uint8Array. Senza questa conversione fallisce
// senza un messaggio utile, ed e' l'errore piu' comune in assoluto.
function base64UrlToUint8Array(s) {
  const pad = '='.repeat((4 - (s.length % 4)) % 4);
  const b64 = (s + pad).replace(/-/g, '+').replace(/_/g, '/');
  const grezzo = atob(b64);
  return Uint8Array.from(grezzo, (c) => c.charCodeAt(0));
}

btnAttiva.addEventListener('click', async () => {
  // Da un TOCCO, e senza await prima: un'attesa qui rompe il legame col
  // gesto e su iOS la richiesta viene ignorata in silenzio.
  const permesso = await Notification.requestPermission();
  if (permesso !== 'granted') return;

  // ready attende un worker ATTIVO: register() da solo puo' restituirne uno
  // ancora in installazione, e subscribe() su quello fallisce senza dire perche'.
  const reg = await navigator.serviceWorker.ready;

  // Su iPhone in Safari (app NON installata) pushManager non esiste affatto.
  // Non e' un guasto: e' il modello di Apple, ed e' il caso piu' frequente.
  if (!reg.pushManager) return;

  const { chiave } = await (await fetch('/api/chiave-pubblica')).json();
  const sub = await reg.pushManager.subscribe({
    userVisibleOnly: true,  // obbligatorio su Chrome, e coerente con la regola
    applicationServerKey: base64UrlToUint8Array(chiave),
  });

  await fetch('/api/iscrivi', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ iscrizione: sub.toJSON() }),
  });
});

Invio, lato server

server.js

const webpush = require('web-push');
// Il soggetto dev'essere un mailto: o un https: veri: identifica chi gestisce
// il servizio verso Google e Apple.
webpush.setVapidDetails(SOGGETTO, CHIAVE_PUBBLICA, CHIAVE_PRIVATA);

async function spedisci(voce, carico) {
  try {
    // TTL 24h: una notifica piu' vecchia di un giorno non interessa piu' a
    // nessuno, e il servizio push puo' smettere di riprovare.
    await webpush.sendNotification(
      { endpoint: voce.endpoint, keys: voce.keys }, carico,
      { TTL: 86400, urgency: 'high' }
    );
    return { ok: true };
  } catch (e) {
    // 404/410 = quell'iscrizione non esiste piu' (app disinstallata, permesso
    // revocato). Vanno CANCELLATE: e' l'unico modo che il protocollo offre per
    // sapere che un dispositivo se n'e' andato. Chi non lo fa accumula invii
    // falliti per sempre.
    if (e.statusCode === 404 || e.statusCode === 410) iscrizioni.rimuovi(voce.endpoint);
    return { ok: false, stato: e.statusCode };
  }
}

Servire il service worker

server.js

app.get('/sw.js', (req, res) => {
  res.set({
    'Content-Type': 'application/javascript; charset=utf-8',
    // Senza questo il browser puo' servire per ore un worker vecchio, e una
    // correzione al gestore push sembrerebbe non avere alcun effetto.
    'Cache-Control': 'no-cache, max-age=0',
    'Service-Worker-Allowed': '/',
  });
  res.sendFile(path.join(__dirname, 'sw.js'));
});

7Guidare l'installazione

Su iPhone non si può automatizzare. Si può però rendere il gesto ovvio.

Esistono due librerie mature — @khmyznikov/pwa-install e philfung/add-to-homescreen, entrambe MIT. Qui è stato scritto un componente proprio, per una ragione precisa: entrambe si fermano all'installazione, mentre il percorso vero è installa → concedi il permesso, e su iPhone il secondo esiste solo dopo il primo. Una libreria che copre metà del problema va comunque estesa.

Ne sono state prese però le decisioni, che valgono più del codice:

Quale invito mostrare

L'ordine delle domande conta: i browser in-app si riconoscono prima di chiedersi se si è su iPhone, perché sono il caso più frequente da social e quello in cui installare è impossibile.

I casi da gestire, tutti

8I link nell'app installata

«Se la PWA è installata, il link deve aprirla»: sì su Android, mai su iOS.

Cosa mettere nel manifest, dove funziona:

• handle_links: "preferred" — l'utente può sempre annullarlo dalle impostazioni dell'app: è una preferenza, non una garanzia, e un'interfaccia che la dà per certa mente;
• launch_handler: { client_mode: "navigate-existing" } — porta all'indirizzo la finestra già aperta invece di aprirne una seconda;
• related_applications: [{ platform: "webapp", url: "<url assoluto del manifest>" }] — abilita getInstalledRelatedApps() a riconoscere sé stessa.

Infine: non esiste alcuna API per lanciare la PWA installata da una pagina di browser. La cattura avviene prima, a livello di sistema: se il link è già aperto nel browser, è tardi. Il massimo onesto è riconoscerlo e dire di aprirla dall'icona. E su Android il WebAPK si aggiorna con ritardo — fino a circa un giorno — quindi handle_links non ha effetto immediato sulle installazioni esistenti.

9L'apparato di misura

La domanda da farsi prima di dichiarare pronto un banco di prova: se fallisce, da dove leggo il perché?

Se la risposta è «lo chiedo a chi ha in mano il telefono», gli strumenti mancano e il lavoro non è finito — perché quella persona risponderà «non è arrivata», che è l'informazione che si aveva già.

Qui l'esperimento scrive il proprio verbale. Le righe che contano di più le scrive il dispositivo, non il server:

L'invio differito

Un pulsante «invia adesso» dimostra che il giro funziona, ma con l'app in primo piano non prova che la notifica arrivi da fuori. Serve un invio differito di dieci secondi: il server risponde 202 subito — la risposta deve arrivare prima che l'utente chiuda l'app, o vedrebbe un errore di rete proprio mentre fa la cosa giusta — e spedisce dopo. Sullo schermo parte un conto alla rovescia, che serve a una cosa sola: dire all'utente che deve chiudere l'app adesso.

Se l'utente ha chiuso davvero, il messaggio finale non lo leggerà mai. Ed è esattamente il caso in cui la prova sta riuscendo.

10Sicurezza

Un endpoint che agisce verso l'esterno nasce chiuso, non viene chiuso dopo.

Le rotte si separano per ampiezza dell'effetto, non per comodità. È questa separazione a permettere di avere insieme un pulsante di prova funzionante sul telefono e nessun endpoint sfruttabile da estranei:

• La chiave privata VAPID firma le notifiche a nome del sito: permessi 0600, mai nei commit, mai nei log. Rigenerarla invalida tutte le iscrizioni, perché i dispositivi sono legati alla vecchia chiave pubblica.
• Gli endpoint push nel verbale vanno troncati: sono la credenziale con cui si spedisce a quel dispositivo. Ne bastano le ultime cifre per riconoscere «lo stesso telefono di prima».
• Niente basic auth davanti a una PWA: manda in errore il download del service worker e del manifest, e su iOS impedisce del tutto l'aggiunta alla schermata Home.
• La CSP deve includere worker-src 'self', o il browser blocca il service worker e non arriva nessuna notifica.

11Le trappole

Sintomo a sinistra, causa quasi certa a destra.

12Ordine di lavoro

Scritto per un agente che debba costruire un'applicazione simile da zero.

1. Verifica il dominio prima di tutto. Serve un record DNS e un certificato valido. Senza, non si può provare nulla di ciò che conta: iOS non installa e le notifiche non partono. È il passo 1, non l'ultimo.
2. Documentati su fonti primarie. Il supporto al Web Push su iOS è cambiato più volte; quello che un modello «sa» a memoria è vecchio per costruzione. Salva la nota così non va rifatto.
3. Manifest, icone, service worker — nell'ordine. Il service worker dalla radice, con Service-Worker-Allowed: /.
4. Chiavi VAPID e archivio iscrizioni. Le chiavi di produzione nascono sul server e non transitano dal repository.
5. Il registro degli eventi, adesso e non dopo. Costruirlo alla fine significa aver lavorato al buio fino a quel momento.
6. Percorso utente: rilevamento piattaforma, invito all'installazione, permesso da un tocco, iscrizione.
7. Test automatici — sapendo cosa non dimostrano. Vale la pena eseguire il service worker con payload diversi, non leggerne il sorgente.
8. Deploy idempotente: processo sul solo loopback, reverse proxy davanti, segreti generati sul server e mai sovrascritti da un aggiornamento.
9. La prova sul telefono vero. È l'unica che conta, ed è l'unica che un agente non può fare da solo.
10. Scrivi gli esiti, compresi i fallimenti. Un esperimento che documenta solo i successi non è un esperimento.

Prima di dire che è finito

• Android Chrome: installazione in un tocco, notifica ricevuta ad app chiusa
• Android: dopo un rifiuto il pulsante «Installa» non resta acceso e morto
• iPhone Safari non installata: il pulsante notifiche è spento con la spiegazione
• iPhone installata: notifica ricevuta a schermo bloccato
• Aperto da Instagram: dice di uscire, non finge che si possa installare
• Il verbale contiene almeno un notifica-mostrata per ciascun telefono
• /api/invia senza token risponde 401
• prefers-reduced-motion: le animazioni informative si fermano ma non spariscono

13Gli esiti misurati

Non stime: numeri letti dal verbale, prodotti da un iPhone reale.

Le tre prove differite sono partite dieci secondi dopo il tocco, ad app chiusa, e sono comparse circa un secondo dopo: la latenza vera di APNs è quel secondo, non gli undici. Zero invii falliti, zero iscrizioni perse.

Due difetti trovati dal verbale, non dall'occhio

1. In Safari con l'app non installata, il registro segnava «service worker in errore». Era un falso allarme: su iOS registration.pushManager non esiste finché l'app non è installata. Uno strumento che segnala guasti inesistenti è peggio di uno strumento assente.
2. black-translucent faceva scorrere il contenuto sotto la barra di stato: ora e batteria finivano sopra i pulsanti. Nessun test automatico l'avrebbe preso — è un difetto che si vede solo guardando.

14Fonti

Primarie, con la data della verifica. Vanno riconfermate a ogni major di iOS.

• Web Push for Web Apps on iOS and iPadOS — WebKit. Supporto da iOS 16.4, solo per web app aggiunte alla Home, permesso solo in risposta a un'interazione diretta.
• Push API — MDN.
• web-push — la libreria di invio, versione 3.6.7.
• Navigation management into installed PWAs — Chrome. launch_handler da Chrome 110, cattura dei link da Chrome 139 su desktop.
• pwa-url-handler explainer — WICG. handle_links.
• Get Installed Related Apps API — Chrome.
• khmyznikov/pwa-install e philfung/add-to-homescreen — MIT, le due librerie da cui sono state prese le decisioni d'interfaccia.