Aggiungi un file manifest di un'app web

Supporto dei browser

  • 39
  • 79
  • x
  • x

Fonte

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.
Esempio di finestra PWA con visualizzazione autonoma.
L'interfaccia utente autonoma.
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.
Esempio di finestra PWA con un display dell'interfaccia utente minima.
L'UI minimale.
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 predefinito scope 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'attributo scope.
  • 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.

Esempio di finestra PWA con tema_color personalizzato.
Esempio di finestra PWA con theme_color personalizzato.

theme_color nelle query supporti

Supporto dei browser

  • 93
  • 93
  • 106
  • 15

Fonte

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".
  • In Chrome 109, gli screenshot con l'elemento form_factor impostato su "wide" vengono ignorati su Android. Gli screenshot senza form_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.

Screenshot dell&#39;interfaccia utente di installazione più completa su computer e dispositivi mobili.
UI di installazione più completa su computer e dispositivi mobili.

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.

Il riquadro dell&#39;applicazione in Chrome DevTools con la scheda manifest selezionata.
Testa il manifest in 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.