Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiungi un file manifest di un'app web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Supporto dei browser

Origine

Un manifest della web app è un file JSON che indica al browser il comportamento della tua Progressive Web App (PWA) quando è installata sul computer o sul dispositivo mobile dell'utente. Un file manifest tipico include almeno:

Il nome dell'app
Le icone che l'app deve utilizzare
L'URL che deve essere aperto all'avvio dell'app

Crea il file manifest

Il file manifest può avere un nome qualsiasi, ma in genere si chiama manifest.json e viene visualizzato dalla directory principale (la directory di primo livello del tuo sito web). La specifica suggerisce che l'estensione debba essere .webmanifest, ma ti consigliamo di utilizzare i file JSON per rendere i manifest più facili da leggere.

Un tipico file manifest 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à manifest principali

`short_name` e `name`

Devi fornire almeno uno dei valori short_name o name nel file manifest. Se fornisci entrambi, name viene utilizzato quando l'app viene installata, mentre short_name viene utilizzata nella schermata Home, in Avvio app o in altre posizioni in cui lo spazio è limitato dell'utente.

`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 image. Ogni oggetto deve includere src, una proprietà sizes e type dell'immagine. Per utilizzare le icone mascherabili, a volte chiamate icone adattive su Android, aggiungi "purpose": "any maskable" alla proprietà icon.

Per Chromium, devi fornire almeno un'icona di 192 x 192 pixel e un'icona di 512 x 512 pixel. Se vengono fornite solo queste due dimensioni per le icone, Chrome ridimensiona automaticamente le icone per adattarle al dispositivo. Se preferisci ridimensionare le tue icone e regolarle per una precisione pixel, fornisci le icone con incrementi di 48 dp.

`id`

La proprietà id ti 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 aggiornarli in futuro. Per ulteriori informazioni, consulta Identificazione univoca delle PWA con la proprietà ID manifest dell'app web.

`start_url`

start_url è una proprietà obbligatoria. Indica al browser dove deve avviarsi l'app al suo avvio e impedisce all'app di avviarsi sulla pagina in cui si trovava l'utente quando ha aggiunto l'app alla schermata Home.

Il start_url deve indirizzare l'utente direttamente alla tua app, non alla pagina di destinazione di un prodotto. Pensa a ciò che l'utente vuole fare subito dopo aver aperto la tua app e inseriscilo lì.

`background_color`

La proprietà background_color viene utilizzata nella schermata iniziale quando l'applicazione viene avviata per la prima volta su dispositivo mobile.

`display`

Puoi personalizzare l'interfaccia utente del browser visualizzata al momento dell'avvio dell'app. Ad esempio, puoi nascondere la barra degli indirizzi e gli elementi dell'interfaccia utente del browser. I giochi possono anche essere avviati a schermo intero. La proprietà display assume 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 che abbia l'aspetto di un'app autonoma. L'app viene eseguita in una propria finestra, separata dal browser, e nasconde gli elementi standard dell'interfaccia utente del browser, come la barra degli indirizzi. UI autonoma.
`minimal-ui`	Questa modalità è simile a `standalone`, ma fornisce all'utente un insieme minimo di elementi dell'interfaccia utente per controllare la navigazione, come i pulsanti Indietro e Ricarica. L'interfaccia utente minima.
`browser`	Un'esperienza di browser standard.

`display_override`

Per scegliere la modalità di visualizzazione dell'app web, imposta una modalità display nel file manifest come spiegato in precedenza. I browser non sono tenuti a 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à, passano alla modalità di visualizzazione successiva della catena. In alcuni casi rari, questi valori di riserva possono causare problemi. Ad esempio, uno sviluppatore non può richiedere "minimal-ui" senza essere forzato a tornare alla modalità di visualizzazione "browser" quando "minimal-ui" non è supportato. Il comportamento attuale rende inoltre impossibile introdurre nuove modalità di visualizzazione in modo compatibile con le versioni precedenti, perché non hanno un posto nella catena di riserva.

Puoi impostare la tua sequenza di riserva utilizzando la proprietà display_override, che il browser prende in considerazione 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 non sono supportati, il browser ricorre alla valutazione del campo display. Se non è presente alcun campo display, il browser ignora display_override.

Di seguito è riportato un esempio di utilizzo di display_override. I dettagli di "window-control-overlay" non rientrano nell'ambito di questa pagina.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Quando carica questa app, il browser tenta di utilizzare prima "window-control-overlay". Se non è disponibile, viene utilizzato "minimal-ui" e poi "standalone" dalla proprietà display. Se nessuna di queste opzioni è disponibile, il browser torna alla catena di fallback standard.

`scope`

Il scope della tua app è l'insieme di URL che il browser considera parte della tua app. scope controlla la struttura dell'URL che include tutti i punti di entrata e di uscita dell'app e il browser lo utilizza per determinare quando l'utente ha abbandonato l'app.

Alcune altre note relative a scope:

Se non includi un scope nel manifest, il valore predefinito implicito scope è l'URL iniziale, ma con il nome file, la query e il frammento rimossi.
L'attributo scope può essere un percorso relativo (../) o un percorso di livello superiore (/) che consenta di aumentare la copertura delle navigazioni nella tua app web.
start_url deve essere 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`

theme_color imposta il colore della barra degli strumenti e può essere visualizzato nell'anteprima dell'app nei selettori di attività. Il colore theme_color deve corrispondere al colore del tema meta specificato nell'intestazione del documento.

`theme_color` nelle query supporti

Supporto dei browser

Origine

Puoi modificare theme_color in una media query utilizzando l'attributo media dell'elemento colore tema meta. Ad esempio, in questo modo puoi definire un colore per la modalità chiara e un altro per la modalità scura. Tuttavia, non puoi definire queste preferenze nel manifest. Per maggiori informazioni, consulta il problema di 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 per app che forniscono un accesso rapido alle attività chiave all'interno dell'app. Ogni elemento è un dizionario contenente 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 carattere di punto di sospensione. Su Android, la descrizione deve inoltre utilizzare un massimo di 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 ampi o su "narrow" per gli screenshot solo stretti.

In Chrome, l'immagine deve soddisfare i seguenti criteri:

La larghezza e l'altezza devono essere di almeno 320 px e di massimo 3840 px.
La dimensione massima non può essere più di 2,3 volte la lunghezza della dimensione minima.
Tutti gli screenshot corrispondenti al fattore di forma appropriato devono avere le stesse proporzioni.
- A partire da Chrome 109, su computer vengono visualizzati solo gli screenshot con form_factor impostato su "wide".
A partire da Chrome 109, gli screenshot con l'opzione form_factor impostata su "wide" vengono ignorati su Android. Gli screenshot senza form_factor vengono comunque mostrati per motivi di compatibilità con le versioni precedenti.

Chrome su computer mostra almeno uno e al massimo otto screenshot che soddisfano questi criteri. Le altre vengono ignorate.

Chrome su Android mostra almeno uno e massimo cinque screenshot che soddisfano questi criteri. Il resto viene ignorato.

Screenshot dell'interfaccia utente di installazione più completa su computer e dispositivi mobili. — UI di installazione più completa su computer e dispositivi mobili.

Aggiungi il manifest dell'app web alle tue pagine

Dopo aver creato il file manifest, aggiungi un tag <link> a tutte le pagine della tua app web progressiva. Ad esempio:

<link rel="manifest" href="/manifest.json">

La richiesta del file manifest viene effettuata senza credenziali, anche se si trova nello stesso dominio. Se il manifest richiede credenziali, devi includere crossorigin="use-credentials" nel tag manifest.

Testare il manifest

Per verificare che il manifest sia configurato correttamente, utilizza il riquadro Manifest nel riquadro Applicazione di Chrome DevTools.

Il riquadro delle applicazioni in Strumenti per sviluppatori di Chrome con la scheda manifest selezionata. — Esegui il test del manifest in DevTools.

Questo riquadro fornisce una versione leggibile da parte dell'utente di molte proprietà del file manifest e ti consente di verificare che tutte le immagini vengano caricate correttamente.

Schermate iniziali sui dispositivi mobili

Quando l'app viene lanciata per la prima volta su dispositivo mobile, può essere necessario un istante prima che il browser inizi e che i contenuti iniziali inizino a essere visualizzati. Invece di mostrare una schermata bianca che potrebbe far pensare all'utente che l'app non funzioni, il browser mostra una schermata iniziale fino al primo rendering.

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 più adatta alla risoluzione del dispositivo per le schermate di benvenuto. Nella maggior parte dei casi è sufficiente fornire icone di 192 px e 512 px, ma puoi fornire icone aggiuntive per una migliore corrispondenza.

Per approfondire

Per scoprire altre proprietà che puoi aggiungere al manifest dell'app web, consulta la documentazione MDN sul manifest dell'app web.

Aggiungi un file manifest di un'app web

Crea il file manifest

Proprietà manifest principali

short_name e name

icons

id

start_url

background_color

display

display_override

scope

theme_color

theme_color nelle query supporti

shortcuts

description

screenshots