Il Web App Manifest

Il manifest di un'app web è un file JSON che indica al browser come installare la pagina come app: quale nome usare, quale icona visualizzare, quale URL avviare, quale combinazione di colori applicare e quale modalità di visualizzazione utilizzare (standalone, fullscreen, browser).

Faccia riferimento al manifest da ogni pagina che deve poter essere installata: <link rel="manifest" href="/manifest.webmanifest"> nell'head. Il browser lo recupera una volta e lo memorizza nella cache; gli aggiornamenti del manifest vengono rilevati nei caricamenti successivi.

Perché il browser proponga "Installa app", il manifest deve contenere almeno: name (nome completo), short_name (etichetta della schermata Home, circa 12 caratteri), start_url, display (di solito "standalone") e un array icons con almeno un PNG 192x192 e uno 512x512.

L'URL avviato quando si tocca l'icona dell'app installata. Spesso è / per la pagina iniziale, ma può includere parametri di query per l'analisi: "start_url": "/?source=pwa" distingue le sessioni provenienti dall'app installata da quelle nel browser.

display può essere "browser" (interfaccia normale della pagina), "minimal-ui" (parte dell'interfaccia), "standalone" (nessuna interfaccia del browser: l'app sembra un'app nativa) o "fullscreen" (nessuna barra di stato). standalone è la scelta tipica per una PWA.

Includa un'icona con purpose "maskable", così Android può adattarla alla forma delle altre icone della schermata Home: { src: "/icon-mask.png", sizes: "192x192", purpose: "maskable" }. Le icone maskable includono un'area sicura che consente al sistema di ritagliare l'immagine.

theme_color imposta la tonalità della barra degli indirizzi quando l'app è in esecuzione nel browser. background_color viene mostrato come sfondo della schermata iniziale prima del caricamento della pagina. Abbini questi valori ai colori principali del sistema di design per ottenere un avvio curato.

"orientation": "portrait" blocca l'app in orientamento verticale quando è installata. "any", "landscape" e "portrait-primary" sono alternative. La maggior parte delle PWA generiche lascia questo campo non impostato e lascia decidere l'orientamento al dispositivo.

Perché il browser mostri "Installa", la pagina deve essere fornita tramite HTTPS, registrare un service worker che gestisca gli eventi fetch, collegare un manifest valido con i campi minimi e soddisfare i criteri di coinvolgimento, ad esempio l'interazione dell'utente con la pagina.

I browser memorizzano il manifest nella cache. Per forzarne l'aggiornamento dopo una modifica, cambi gli URL delle icone, eventualmente utilizzando un parametro di query per invalidare la cache, oppure attenda: la maggior parte dei browser esegue nuovi controlli periodicamente. Non esiste un'API per forzare l'aggiornamento; progetti considerando che gli utenti potrebbero utilizzare per un po' un manifest leggermente obsoleto.

La scheda Application di Chrome DevTools mostra il manifest analizzato, i valori calcolati e gli errori di validazione. L'audit PWA di Lighthouse verifica ogni requisito per l'installazione e segnala ciò che manca. Utilizzi entrambi gli strumenti durante lo sviluppo per confermare l'idoneità all'installazione.

Che cosa fa il valore display: "standalone" in un manifest di un'app web?

Il manifest di un'app web (manifest.webmanifest) indica al browser come installare la pagina come app: name, short_name, start_url, display, theme_color e icone (192 e 512, oltre a una maskable per Android). Lo colleghi tramite <link rel="manifest">, si assicuri di utilizzare HTTPS e un service worker per consentire l'installazione e verifichi il risultato in Chrome DevTools e nell'audit PWA di Lighthouse.