Il file manifest di un'app web è un file JSON che indica al browser il comportamento dell'app web progressiva (PWA) quando è installata sul computer o sul dispositivo mobile dell'utente. Come minimo, un tipico file manifest include:
- Il nome dell'app
- Le icone che dovrebbe utilizzare l'app
- L'URL da aprire all'avvio dell'app
Crea il file manifest
Il file manifest può avere qualsiasi nome, ma in genere è denominato manifest.json
e viene pubblicato dalla directory principale (la directory di primo livello del tuo sito web). La specifica suggerisce che l'estensione deve essere .webmanifest
, ma ti consigliamo di utilizzare file JSON per rendere più chiari la lettura dei manifest.
Un manifest tipico ha il seguente aspetto:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
Proprietà del manifest chiave
short_name
e name
Devi fornire almeno un valore tra short_name
o name
nel tuo file manifest. Se fornisci entrambi, name
viene utilizzato quando l'app è installata e short_name
nella schermata Home dell'utente, in Avvio app o in altre situazioni in cui lo spazio è limitato.
icons
Quando un utente installa la tua PWA, puoi definire un insieme di icone per il browser da utilizzare nella schermata Home, in Avvio applicazioni, nel selettore di attività, nella schermata iniziale e in altre posizioni.
La proprietà icons
è un array di oggetti immagine. Ogni oggetto deve includere src
, una proprietà sizes
e type
dell'immagine. Per utilizzare le icone mascherabili, a volte note come icone adattive su Android, aggiungi "purpose": "any maskable"
alla proprietà icon
.
Per Chromium, devi fornire un'icona di almeno 192 x 192 pixel e un'icona di 512 x 512 pixel. Se fornisci solo le due dimensioni delle icone, Chrome ridimensiona automaticamente le icone per adattarle al dispositivo. Se preferisci ridimensionare le tue icone e regolarle per ottenere la massima precisione dei pixel, fornisci le icone con incrementi di 48 dp.
id
La proprietà id
consente di definire esplicitamente l'identificatore utilizzato per
la tua applicazione. L'aggiunta della proprietà id
al manifest rimuove la dipendenza da
start_url
o dalla posizione del manifest e consente di aggiornarle
in futuro. Per maggiori informazioni, consulta
Identificare in modo univoco le PWA con la proprietà dell'ID manifest dell'app web.
start_url
start_url
è una proprietà obbligatoria. Indica al browser dove deve iniziare la tua app all'avvio e impedisce l'avvio dell'app sulla pagina su cui si trovava l'utente quando ha aggiunto l'app alla schermata Home.
start_url
deve indirizzare l'utente direttamente alla tua app, non alla pagina di destinazione
del prodotto. Pensa a cosa vuole fare l'utente subito dopo aver
aperto l'app e posizionalo lì.
background_color
La proprietà background_color
viene utilizzata nella schermata iniziale quando
l'applicazione viene avviata sui dispositivi mobili per la prima volta.
display
Puoi personalizzare la UI del browser visualizzata all'avvio dell'app. Ad
esempio, puoi nascondere la barra degli indirizzi e gli elementi dell'interfaccia utente del browser. È anche possibile far partire i giochi
a schermo intero. La proprietà display
accetta uno dei
seguenti valori:
Proprietà | Comportamento |
---|---|
fullscreen |
Apre l'app web senza UI del browser e occupa tutta l'area di visualizzazione disponibile. |
standalone |
Apre l'app web in modo da sembrare un'app autonoma. L'app viene eseguita in una propria finestra, separata dal browser, e nasconde elementi standard dell'interfaccia utente del browser, come la barra degli indirizzi. |
minimal-ui |
Questa modalità è simile a standalone , ma fornisce all'utente un insieme minimo di elementi UI per il controllo della navigazione, ad esempio i pulsanti Indietro e Ricarica.
|
browser |
Un'esperienza browser standard. |
display_override
Per scegliere la modalità di visualizzazione della tua app web, imposta una modalità display
nel file manifest, come spiegato in precedenza. I browser non devono supportare tutte le modalità di visualizzazione, ma devono supportare la catena di riserva definita dalle specifiche ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
). Se non supportano una determinata modalità, tornano alla modalità di visualizzazione successiva nella catena. In
rari casi, questi fallback possono causare problemi. Ad esempio, uno sviluppatore non può richiedere "minimal-ui"
senza essere forzato nuovamente alla modalità di visualizzazione "browser"
quando "minimal-ui"
non è supportato. Il comportamento attuale rende anche
impossibile introdurre nuove modalità di visualizzazione in modo compatibile con le versioni precedenti,
poiché non hanno un posto nella catena di riserva.
Puoi impostare la tua sequenza di riserva utilizzando la proprietà display_override
,
che il browser considera prima della proprietà display
. Il suo valore è una sequenza di stringhe considerate nell'ordine elencato e viene applicata la prima modalità di visualizzazione supportata. Se nessuna è supportata, il browser torna
a valutare il campo display
. Se non è presente alcun campo display
, il browser ignora display_override
.
Di seguito è riportato un esempio di come utilizzare display_override
. I dettagli di "window-control-overlay"
non rientrano nell'ambito di questa pagina.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Durante il caricamento di questa app, il browser prova a utilizzare prima "window-control-overlay"
. Se non è disponibile, torna a "minimal-ui"
, quindi a
"standalone"
dalla proprietà display
. Se nessuna di queste è disponibile, il browser torna alla catena di riserva standard.
scope
Il scope
dell'app è l'insieme di URL che il browser considera parte
dell'app. scope
controlla la struttura dell'URL che include tutti i punti di ingresso e di uscita
dell'app e il browser la utilizza per determinare quando l'utente ha abbandonato l'app.
Alcune altre note su scope
:
- Se non includi un elemento
scope
nel file manifest, il valore implicito predefinitoscope
sarà l'URL di avvio, ma con nome file, query e frammento rimossi. - L'attributo
scope
può essere un percorso relativo (../
) o qualsiasi percorso di livello superiore (/
) che consentirebbe un aumento della copertura delle navigazioni nella tua app web. start_url
deve rientrare nell'ambito.start_url
è relativo al percorso definito nell'attributoscope
.- Un
start_url
che inizia con/
sarà sempre la radice dell'origine.
theme_color
L'elemento theme_color
imposta il colore della barra degli strumenti e può essere visualizzato nell'anteprima dell'app nei cambi attività. theme_color
deve corrispondere al colore del tema meta
specificato nell'intestazione del documento.
theme_color
nelle query supporti
Puoi modificare theme_color
in una query supporti utilizzando l'attributo media
dell'elemento colore del tema meta
. Ad esempio, puoi definire un colore per la modalità Luce
e un altro per la modalità Buio in questo modo. Tuttavia, non puoi definire queste preferenze nel file manifest. Per maggiori informazioni, consulta il problema relativo a GitHub w3c/manifest#975.
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
La proprietà shortcuts
è un array di oggetti scorciatoia dell'app che consentono di accedere rapidamente alle attività chiave all'interno della tua app. Ogni membro è un dizionario che contiene almeno un name
e un url
.
description
La proprietà description
descrive lo scopo della tua app.
In Chrome, la lunghezza massima della descrizione è di 300 caratteri su tutte le piattaforme. Se la descrizione è più lunga, il browser la tronca con un puntini di sospensione. Su Android la descrizione deve utilizzare al massimo sette righe di testo.
screenshots
La proprietà screenshots
è un array di oggetti immagine che rappresentano la tua app in scenari di utilizzo comuni. Ogni oggetto deve includere src
, una proprietà sizes
e type
dell'immagine. La proprietà form_factor
è facoltativa.
Puoi impostarlo su "wide"
per gli screenshot applicabili solo agli schermi larghi o su "narrow"
per solo gli screenshot più piccoli.
In Chrome, l'immagine deve soddisfare i seguenti criteri:
- La larghezza e l'altezza devono essere comprese tra 320 px e 3840 px.
- La dimensione massima non può essere più di 2,3 volte la lunghezza della dimensione minima.
- Tutti gli screenshot che corrispondono al fattore di forma appropriato devono avere le stesse proporzioni.
- A partire da Chrome 109, sui computer vengono visualizzati solo gli screenshot con l'opzione
form_factor
impostata su"wide"
.
- A partire da Chrome 109, sui computer vengono visualizzati solo gli screenshot con l'opzione
- In Chrome 109, gli screenshot con l'elemento
form_factor
impostato su"wide"
vengono ignorati su Android. Gli screenshot senzaform_factor
vengono comunque visualizzati per motivi di compatibilità con le versioni precedenti.
Chrome per computer desktop visualizza almeno uno e massimo otto screenshot che soddisfano questi criteri. Gli altri vengono ignorati.
Chrome su Android mostra almeno uno e al massimo cinque screenshot che soddisfano questi criteri. Gli altri vengono ignorati.
Aggiungi il manifest dell'app web alle tue pagine
Dopo aver creato il manifest, aggiungi un tag <link>
a tutte le pagine dell'app web progressiva, ad esempio:
<link rel="manifest" href="/manifest.json">
Testare il manifest
Per verificare che il file manifest sia configurato correttamente, utilizza il riquadro Manifest nel riquadro Applicazione di Chrome DevTools.
Questo riquadro fornisce una versione leggibile di molte delle proprietà del tuo manifest e ti consente di verificare che tutte le immagini vengano caricate correttamente.
Schermate iniziali su dispositivi mobili
Quando l'app viene lanciata per la prima volta su un dispositivo mobile, l'avvio del browser e il rendering dei contenuti iniziali possono richiedere alcuni istanti. Anziché mostrare una schermata bianca che potrebbe far credere all'utente che l'app non funzioni, il browser mostra una schermata iniziale fino alla prima visualizzazione.
Chrome crea automaticamente la schermata iniziale dai campi name
,
background_color
e icons
specificati nel file manifest. Per creare una transizione fluida dalla schermata iniziale all'app, imposta background_color
dello stesso colore della pagina di caricamento.
Chrome sceglie l'icona che più si avvicina alla risoluzione del dispositivo per le schermate iniziali. Fornire icone da 192 px e 512 px è sufficiente nella maggior parte dei casi, ma puoi fornire icone aggiuntive per una corrispondenza migliore.
Per approfondire
Per scoprire di più sulle altre proprietà che puoi aggiungere al file manifest dell'app web, consulta la documentazione relativa al file manifest per app web MDN.