File manifest dell'app web

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 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 consentire al browser di rilevare 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. È 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

  1. Nel riquadro a sinistra, in Application (Applicazione), seleziona Manifest (Manifesto).
  2. Controlla i campi del manifest analizzati dal browser.

Per Firefox

  1. Apri lo strumento di controllo.
  2. Vai alla scheda Applicazione.
  3. Seleziona l'opzione Manifest nel riquadro a sinistra.
  4. Verifica che i campi del file manifest vengano 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 determinare come si avvia. 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, sizes e purpose facoltativi, 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-ui o browser, che descrive in che modo il sistema operativo deve disegnare la finestra della PWA. Per ulteriori informazioni sulle diverse modalità di visualizzazione, consulta il capitolo Design dell'app. La maggior parte dei casi d'uso implementa standalone.
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_url come valore di riserva. Tieni presente che, se in futuro modifichi start_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, le icone più vicine alle specifiche richieste.

Se devi scegliere una sola dimensione per l'icona, la dimensione deve essere 512 x 512 pixel. Tuttavia, si consiglia di fornire più dimensioni, tra cui anche immagini 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.

L&#39;area sicura contrassegnata come un cerchio centrato con raggio del 40% all&#39;interno dell&#39;icona quadrata

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.

Un&#39;icona non adatta a un&#39;icona mascherabile.

Questa immagine potrebbe essere resa utilizzabile con un maggiore spazio interno.

L&#39;icona con più spaziatura interna è adatta per le maschere.

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 gratuito per testare e creare una versione mascherabile dell'icona.

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 all'interno della finestra dell'app installata. Ad esempio, se colleghi una pagina esterna all'ambito, il rendering verrà eseguito in un browser in-app anziché nella finestra della PWA. Tuttavia, l'ambito del service worker non verrà modificato.

L'immagine successiva mostra come viene utilizzato il campo theme_color per la barra del titolo su un computer quando installi una PWA.

La stessa PWA installata su computer con un tema di colore diverso.

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, viene visualizzata un'immagine statica durante 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 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.

Una PWA sulla schermata iniziale di Android che prende valori diversi dal file manifest.

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 en per l'inglese, pt-BR per il portoghese brasiliano o in per l'hindi.
dir
La direzione di visualizzazione dei campi manifest che supportano la direzione (ad esempio name, short_name e description). I valori validi sono auto, ltr (da sinistra a destra) e rtl (da destra a sinistra).
orientation
Orientamento desiderato per l'app una volta installata. Un gioco potrebbe impostare questa impostazione per richiedere un orientamento solo orizzontale. Sono accettati diversi valori, ma se sono inclusi, in genere sono portrait o landscape esplicitamente.

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, type e sizes (simile all'oggetto icons) 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 disponibile. È destinata a essere utilizzata per determinare le età per le quali la PWA è appropriata.

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.

Risorse