Il file manifest dell'app web è un file creato da te che indica al browser come vuoi che i tuoi contenuti web vengano visualizzati come app nel sistema operativo. Il file manifest può includere informazioni di base come il nome dell'app, l'icona e il colore del tema, preferenze avanzate, ad esempio l'orientamento e le scorciatoie dell'app desiderati, nonché metadati del catalogo, come gli screenshot.
Ogni PWA deve includere un singolo manifest per applicazione, in genere ospitato nella cartella principale e collegato a tutte le pagine HTML da cui è possibile installare la PWA. L'estensione ufficiale è .webmanifest, quindi potresti assegnare al manifest un nome simile a app.webmanifest.
Aggiunta del manifest di un'app web alla PWA
Per creare il file manifest di un'app web, crea prima un file di testo con un oggetto JSON che contenga almeno un campo name con un valore stringa:
app.webmanifest:
{
"name": "My First Application"
}
Tuttavia, creare il file non è sufficiente, e anche il browser deve sapere che esiste.
Collegamento al manifest
Per comunicare al browser il file manifest dell'app web, devi collegarlo alla PWA utilizzando un elemento HTML <link> e l'attributo rel impostato su manifest in tutte le pagine HTML della PWA. La procedura è simile a quella per collegare un foglio di stile CSS a un documento.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
Debug del manifest
Per assicurarti che il file manifest sia configurato correttamente, puoi utilizzare Inspector in Firefox e DevTools in ogni browser basato su Chromium.
Per i browser Chromium
In DevTools
- Nel riquadro a sinistra, in Applicazione, seleziona Manifest.
- Controlla i campi del manifest analizzati dal browser.
Per Firefox
- Apri Inspector.
- Vai alla scheda Applicazione.
- Seleziona l'opzione Manifest nel riquadro a sinistra.
- Controlla i campi del manifest analizzati dal browser.
Progettare l'esperienza con le PWA
Ora che la PWA è collegata al relativo manifest, è il momento di compilare gli altri campi per definire l'esperienza per gli utenti.
Campi di base
Il primo insieme di campi rappresenta le informazioni principali sulla PWA. Vengono utilizzati per creare l'icona e la finestra della PWA installata e per determinare come viene avviata. Questi sono:
name- Nome completo della tua PWA. Apparirà insieme all'icona nella schermata Home, in Avvio app, sul dock o nel menu del sistema operativo.
short_name- Facoltativo, un nome più breve della tua PWA, utilizzato quando lo spazio non è sufficiente per visualizzare il valore completo del campo
name. Deve contenere meno di 12 caratteri per ridurre al minimo le possibilità di troncamento. icons- Array di oggetti icona con campi
src,type,sizesepurposefacoltativi che descrivono quali immagini devono rappresentare la PWA. start_url- L'URL che la PWA dovrebbe caricare quando l'utente la avvia dall'icona installata. Ti consigliamo un percorso assoluto, quindi se la home page della PWA è la directory principale del tuo sito, puoi impostarlo su "/" per aprirlo all'avvio dell'app. Se non fornisci un URL di avvio, il browser può utilizzare l'URL da cui è stata installata la PWA per iniziare. Può essere un link diretto, ad esempio i dettagli di un prodotto, anziché la schermata Home.
display- Una delle opzioni
fullscreen,standalone,minimal-uiobrowser, che descrive in che modo il sistema operativo deve tracciare la finestra PWA. Per ulteriori informazioni sulle diverse modalità di visualizzazione, consulta il capitolo Design delle app. La maggior parte dei casi d'uso implementastandalone. id- Una stringa che identifica in modo univoco questa PWA rispetto ad altre che potrebbero essere ospitate sulla stessa origine. Se non viene configurato,
start_urlverrà utilizzato come valore di riserva. Tieni presente che se modifichi l'start_urlin futuro (ad esempio quando modifichi il valore di una stringa di query), potresti non essere più in grado di rilevare che una PWA è già installata.
Icone
L'icona della PWA rappresenta l'identità visiva sui dispositivi degli utenti quando è installata, quindi è importante definirne almeno una. Poiché la proprietà icons è una raccolta di oggetti icona, puoi definire diverse icone in diversi formati per offrire agli utenti la migliore esperienza possibile. Ogni browser selezionerà una o più icone in base alle proprie esigenze e al sistema operativo su cui è installato, ovvero quelle più vicine alle specifiche richieste.
Se devi scegliere una sola dimensione per le icone, queste devono essere 512 x 512 pixel. Tuttavia, si consiglia di fornire più dimensioni, includendo anche immagini di dimensioni 192 x 192, 384 x 384 e 1024 x 1024 pixel.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Se non fornisci un'icona o se le dimensioni delle icone non sono consigliate, su alcune piattaforme non verranno superati i criteri di installazione. Su altre piattaforme, l'icona verrà generata automaticamente, ad esempio da uno screenshot della PWA o utilizzando un'icona generica.
Icone mascherabili
Alcuni sistemi operativi, come Android, adattano le icone a dimensioni e forme diverse. Ad esempio, su Android 12, diversi produttori o impostazioni possono cambiare la forma delle icone passando da cerchi a quadrati a quadrati con angoli arrotondati. Per supportare questo tipo di icone adattive, puoi fornire un'icona mascherabile utilizzando il campo purpose.
Per farlo, fornisci un file immagine quadrato la cui icona principale sia contenuta in una "zona sicura", ossia un cerchio centrato nell'icona con un raggio pari al 40% della larghezza dell'icona. (vedi l'immagine di seguito). I dispositivi che supportano le icone mascherabili mascherano l'icona come necessario.
Ecco un esempio di un'icona mascherabile visualizzata in diverse forme di uso comune:
Nell'immagine seguente, se utilizzi l'icona a sinistra come icona mascherabile, i risultati ottenuti sui dispositivi saranno scadenti quando viene applicata una maschera di forma.
Questa immagine potrebbe essere resa utilizzabile con una maggiore spaziatura interna.
Le icone mascherabili devono avere dimensioni minime pari a 512 x 512. Dopo averne creato uno, puoi aggiungerlo alla tua raccolta icons per migliorare l'esperienza per i dispositivi supportati:
"icons": [
{
"src": "/icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "/icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
},
{
"src": "/icons/512-maskable.png",
"type": "image/png",
"sizes": "512x512",
"purpose": "maskable"
},
]
Nella maggior parte dei casi, se l'icona mascherabile non viene visualizzata correttamente, puoi migliorarla aggiungendo più spaziatura interna. Maskable.app è uno strumento online senza costi per testare e creare una versione mascherabile della tua icona.
Campi consigliati
Il prossimo insieme di campi da includere è quello che migliorerà l'esperienza utente, anche se non è obbligatorio per l'installazione.
theme_color- Colore predefinito per l'applicazione; a volte influisce sulla modalità di visualizzazione del sito da parte del sistema operativo (ad esempio, il colore della finestra e della barra del titolo sui computer o il colore della barra di stato sui dispositivi mobili). Questo colore può essere sostituito dall'elemento HTML
theme-color<meta>. background_color- Colore segnaposto da visualizzare sullo sfondo dell'applicazione prima del caricamento del foglio di stile. Attualmente Safari su iOS e iPadOS e la maggior parte dei browser desktop ignorano questo campo.
scope- Modifica l'ambito di navigazione della PWA, consentendoti di definire cosa viene visualizzato nella finestra dell'app installata e cosa no. Ad esempio, se inserisci un link a una pagina esterna all'ambito, il rendering verrà eseguito in un browser in-app anziché all'interno della finestra PWA. Tuttavia, l'ambito del service worker non verrà modificato.
L'immagine successiva mostra come il campo theme_color viene utilizzato per la barra del titolo su un computer quando installi una PWA.
Quando definisci i colori nel file manifest, ad esempio all'interno di theme_color e background_color, devi utilizzare colori con nome CSS, come salmon o orange, colori RGB come #FF5500 o funzioni colore senza trasparenza come rgb() o hsl(). Per ulteriori informazioni, consulta il capitolo Design dell'app.
Prova
Schermate iniziali
Su alcuni dispositivi, viene eseguito il rendering di un'immagine statica mentre è in corso il caricamento della PWA per fornire un feedback immediato all'utente.
Android utilizza i valori theme_color, background_color e icon per generare la schermata iniziale.
Quando installi una PWA su Android, il dispositivo genera una schermata iniziale con le informazioni provenienti dal file manifest, come mostrato nel diagramma seguente.
Safari su iOS e iPadOS, invece, non utilizza il file manifest dell'app web per generare le schermate iniziali. Al contrario, utilizzano un'immagine collegata da un elemento <link> proprietario simile a come gestiscono le icone. Consulta il capitolo Miglioramento per ulteriori dettagli.
Campi estesi
Il successivo insieme di campi offre informazioni aggiuntive sulla PWA. Sono tutti facoltativi.
lang- Un tag della lingua che specifica la lingua principale dei valori del file manifest, ad esempio
enper l'inglese,pt-BRper il portoghese brasiliano oinper l'hindi. dir- La direzione di visualizzazione dei campi manifest che supportano le indicazioni stradali (ad esempio,
name,short_nameedescription). I valori validi sonoauto,ltr(da sinistra a destra) ertl(da destra a sinistra). orientation- Orientamento desiderato per l'app una volta installata. Il gioco può impostare questa opzione in modo da richiedere un orientamento solo orizzontale. Sono accettati diversi valori, ma se inclusi è in genere
portraitolandscapeesplicitamente.
Campi promozionali
Il quarto insieme di campi ti consente di fornire informazioni promozionali sulla tua PWA, ad esempio nei flussi di installazione, nelle schede e nei risultati di ricerca.
description- Una spiegazione di cosa fa la PWA.
screenshots- Array di oggetti screenshot con
src,typeesizes(simile all'oggettoicons) destinato a mostrare la PWA. Non sono previste limitazioni relative alle dimensioni. categories- Array di categorie a cui deve appartenere la PWA da utilizzare come suggerimenti per le schede, facoltativamente dall'elenco di categorie note. Questi valori sono generalmente in minuscolo.
iarc_rating_id- Il codice di certificazione dell'International Age Rating Coalition per la PWA, se ne hai una. È destinato a essere utilizzato per determinare l'età a cui è adatta la PWA.
Puoi vedere questi campi promozionali in azione oggi stesso. Su Android, ad esempio, se la PWA è installabile e fornisci valori almeno per i campi description e screenshots, l'esperienza della finestra di dialogo di installazione si trasforma da una semplice barra delle informazioni "Aggiungi alla schermata Home" a una finestra di dialogo di installazione più completa simile a quella di uno store.
Su Android, puoi ottenere un'interfaccia utente di installazione migliore se fornisci valori per i campi promozionali, come puoi vedere nel prossimo video.
Guarda questi campi promozionali in azione:
Campi delle funzionalità
Infine, è disponibile una serie di campi relativi alle diverse funzionalità che la PWA può utilizzare nei browser supportati, ad esempio i campi shortcuts, share_target e display_overrides, come illustrato nel capitolo Funzionalità. Esistono anche campi, come related_apps e prefer_related_apps (per ulteriori informazioni, consulta il capitolo Rilevamento) per connettere la PWA alle app installate, spesso da uno store.
In futuro potrebbero essere visualizzati molti nuovi campi, mentre i browser aggiungono ulteriori funzionalità alle app web progressive.