Il file manifest dell'app web è un file che crei per indicare 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, l'icona e il colore del tema dell'app, preferenze avanzate come l'orientamento e le scorciatoie per le app e 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 puoi assegnare al file manifest un nome come app.webmanifest.
Aggiunta di un manifest dell'app web alla tua PWA
Per creare un manifest dell'app web, crea innanzitutto un file di testo con un oggetto JSON contenente almeno un campo name con un valore di stringa:
app.webmanifest:
{
"name": "My First Application"
}
Tuttavia, creare il file non è sufficiente, il browser deve sapere anche che esiste.
Collegamento al manifest
Per informare il browser del tuo file manifest dell'app web, devi collegarlo alla tua PWA utilizzando un elemento HTML <link> e l'attributo rel impostato su manifest in tutte le pagine HTML della tua PWA. È simile al modo in cui colleghi 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">
Eseguire il debug del manifest
Per assicurarti che il manifest sia configurato correttamente, puoi utilizzare lo strumento di ispezione in Firefox e DevTools in ogni browser basato su Chromium.
Per i browser Chromium
In DevTools
- Nel riquadro a sinistra, in Application (Applicazione), seleziona Manifest (Manifesto).
- Controlla i campi del manifest analizzati dal browser.
Per Firefox
- Apri lo strumento di controllo.
- Vai alla scheda Applicazione.
- Seleziona l'opzione Manifest nel riquadro a sinistra.
- Controlla i campi del manifest analizzati dal browser.
Progettare l'esperienza PWA
Ora che la tua PWA è collegata al relativo manifest, è il momento di compilare il resto dei campi per definire l'esperienza per i tuoi utenti.
Campi di base
Il primo insieme di campi rappresenta le informazioni di base sulla tua PWA. Vengono utilizzati per creare l'icona e la finestra della PWA installata e per determinare la modalità di avvio. Sono:
name- Nome completo della tua PWA. Verrà visualizzata insieme all'icona nella schermata Home, nel menu, nella barra delle app o nel programma di avvio del sistema operativo.
short_name- Facoltativo, un nome più breve della tua PWA, utilizzato quando non c'è spazio sufficiente per visualizzare il valore completo del campo
name. Non superare i 12 caratteri per ridurre al minimo la possibilità di troncamento. icons- Array di oggetti icona con campi
src,type,sizesepurposefacoltativi, che descrivono le immagini che devono rappresentare la PWA. start_url- L'URL che la PWA deve caricare quando l'utente la avvia dall'icona installata. È consigliabile un percorso assoluto, quindi se la home page della tua PWA è la radice del tuo sito, puoi impostarla su "/" per aprirla all'avvio dell'app. Se non fornisci un URL iniziale, il browser può utilizzare come tale l'URL da cui è stata installata la PWA. Può essere un link diretto, ad esempio i dettagli di un prodotto anziché la schermata Home.
display- Uno dei valori
fullscreen,standalone,minimal-uiobrowser, che descrive in che modo il sistema operativo deve disegnare la finestra della PWA. Per scoprire di più sulle diverse modalità di visualizzazione, consulta il capitolo sul 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 nella stessa origine. Se non è impostato, verrà utilizzato
start_urlcome valore di riserva. Tieni presente che, se in futuro modifichistart_url(ad esempio quando modifichi il valore di una stringa di query), potresti rimuovere la capacità del browser di rilevare che una PWA è già installata.
Icone
L'icona della tua PWA è la sua 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 formati diversi per offrire la migliore esperienza utente possibile. Ogni browser sceglierà una o più icone in base alle proprie esigenze e al sistema operativo su cui è installato, ovvero le icone più vicine alle specifiche richieste.
Se devi scegliere una sola dimensione dell'icona, deve essere di 512 x 512 pixel. Tuttavia, ti consigliamo di fornire più dimensioni, incluse immagini con dimensioni di 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 le icone non sono nelle dimensioni consigliate, su alcune piattaforme non supererai 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, impostazioni o produttori diversi possono modificare la forma delle icone da cerchi a quadrati a quadrati con angoli arrotondati. Per supportare questi tipi di icone adattabili, puoi fornire un'icona mascherabile utilizzando il campo purpose.
A tal fine, fornisci un file immagine quadrato con l'icona principale contenuta in una "zona sicura", 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 maschereranno l'icona in base alle esigenze.
Ecco un esempio di icona mascherabile visualizzata in una serie di forme di uso comune:
Nell'immagine seguente, se utilizzi l'icona a sinistra come icona mascherabile, otterrai risultati scadenti sui dispositivi quando viene applicata una maschera di forma.
Questa immagine potrebbe essere resa utilizzabile con un maggiore spazio interno.
Le icone mascherabili devono avere almeno 512 x 512 pixel. Una volta creato, 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 altro spazio. Maskable.app è uno strumento online senza costi per testare e creare una versione mascherabile dell'icona.
Se l'icona ha scopi generali e può essere mascherata, puoi impostare il campo purpose su "any maskable". Per maggiori dettagli, consulta la documentazione MDN Web App Manifest.
Campi consigliati
Il prossimo insieme di campi da includere migliorerà l'esperienza dell'utente, anche se non sono necessari per l'installabilità.
theme_color- Colore predefinito dell'applicazione, che 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 su 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 del segnaposto da visualizzare nello sfondo dell'applicazione prima del caricamento del relativo foglio di stile. Al momento, 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 e cosa no nella finestra dell'app installata. Ad esempio, se inserisci un link a una pagina esterna all'ambito, questa verrà visualizzata in un browser in-app anziché nella finestra della PWA. Tuttavia, lo scopo del tuo service worker non verrà modificato.
L'immagine seguente mostra come viene utilizzato il campo theme_color 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 i colori con nome CSS, come salmon o orange, i colori RGB come #FF5500 o le funzioni di colore senza trasparenza come rgb() o hsl(). Per ulteriori informazioni, consulta il capitolo sul design delle app.
Prova
Schermate iniziali
Su alcuni dispositivi, durante il caricamento della PWA viene visualizzata un'immagine statica per fornire un feedback immediato all'utente.
Android utilizza i valori theme_color, background_color e icon per generare la schermata di benvenuto.
Quando installi una PWA su Android, il dispositivo genera una schermata iniziale con le informazioni provenienti dal file manifest, come mostrato nel seguente diagramma.
Safari su iOS e iPadOS, invece, non utilizza il file manifest dell'app web per generare schermate iniziali. Utilizzano invece un'immagine collegata da un elemento proprietario <link>, in modo simile a come gestiscono le icone. Per ulteriori dettagli, consulta il capitolo Miglioramenti.
Campi estesi
Il seguente insieme di campi offre ulteriori informazioni sulla tua PWA. Sono tutti facoltativi.
lang- Un tag lingua che specifica la lingua principale dei valori del manifest, ad esempio
enper l'inglese,pt-BRper il portoghese brasiliano oinper l'hindi. dir- La direzione di visualizzazione dei campi manifest che supportano la direzione (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. Un gioco potrebbe impostarlo per richiedere un'orientamento solo orizzontale. Sono accettati diversi valori, ma se sono inclusi, in genere sono
portraitolandscapeesplicitamente.
Campi promozionali
La quarta serie 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) destinati a mostrare la PWA. Non ci sono limitazioni di dimensioni. categories- Array di categorie a cui la PWA deve appartenere da utilizzare come suggerimenti per le schede, eventualmente dall'elenco delle categorie conosciute. Questi valori sono in genere in minuscolo.
iarc_rating_id- Il codice di certificazione dell'International Age Rating Coalition per la PWA, se ne hai uno. È destinato a essere utilizzato per determinare per quali fasce d'età è adatta la tua PWA.
Puoi utilizzare questi campi promozionali già oggi. Ad esempio, su Android, se la tua PWA è installabile e fornisci valori per almeno i campi description e screenshots, l'esperienza della finestra di dialogo di installazione si trasforma da una semplice barra informativa "Aggiungi alla schermata Home" a una finestra di dialogo di installazione più completa, simile a quella di un app store.
Su Android, puoi ottenere un'interfaccia utente di installazione più gradevole se fornisci valori per i campi promozionali, come puoi vedere nel video successivo
Guarda questi campi promozionali in azione:
Campi funzionalità
Infine, esistono diversi campi relativi a funzionalità diverse che la tua PWA può utilizzare nei browser supportati, ad esempio i campi shortcuts, share_target, display_override descritti nel capitolo Funzionalità. Esistono anche campi, come related_apps e prefer_related_apps (per ulteriori informazioni, consulta il capitolo sul rilevamento), per collegare la tua PWA alle app installate, spesso da uno store.
In futuro potrebbero essere visualizzati molti nuovi campi man mano che i browser aggiungono altre funzionalità alle app web progressive.