File manifest dell'app web

Il file manifest dell'app web è un file creato da te che indica al browser in che modo vuoi che i tuoi contenuti web vengano visualizzati come app nel sistema operativo. Il file manifest può includere informazioni di base quali il nome, l'icona e il colore del tema dell'app. preferenze avanzate, quali l'orientamento desiderato e le scorciatoie 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 può essere installata la PWA. La sua estensione ufficiale è .webmanifest, quindi potresti assegnare al tuo manifest un nome simile a app.webmanifest.

Aggiunta di un manifest dell'app web alla PWA

Per creare il file manifest di un'app web, crea innanzitutto un file di testo con un oggetto JSON che contenga almeno un campo name con un valore di stringa:

app.webmanifest:

{
   "name": "My First Application"
}

Tuttavia, la creazione del file non è sufficiente, anche il browser deve sapere 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. Questa procedura è simile a quella per collegare 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">

Debug del manifest

Per assicurarti che il file manifest sia configurato correttamente, puoi utilizzare Inspector in Firefox e DevTools in ogni browser basato su Chromium.

Per i browser Chromium

In DevTools

  1. Nel riquadro a sinistra, in Applicazione, seleziona Manifest.
  2. Verifica che i campi del file manifest vengano analizzati dal browser.

Per Firefox

  1. Apri Inspector.
  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.
di Gemini Advanced.

Progettare l'esperienza con la PWA

Ora che la PWA è collegata al file 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 principali sulla PWA. Vengono utilizzati per creare l'icona e la finestra della PWA installata e determinare come si avvia. Questi sono:

name
Nome completo della PWA. Verrà visualizzata insieme all'icona nella schermata Home, in Avvio app, nel dock o nel menu del sistema operativo.
short_name
(Facoltativo) Un nome più breve della PWA, utilizzato quando non c'è abbastanza spazio per visualizzare il valore completo del campo name. Deve contenere meno di 12 caratteri per ridurre al minimo il rischio di troncamento.
icons
Array di oggetti icona con i campi src, type, sizes e purpose facoltativi, che descrivono quali immagini devono rappresentare la PWA.
start_url
L'URL che la PWA deve caricare quando l'utente la avvia dall'icona installata. È consigliato un percorso assoluto, quindi se la home page della PWA è la directory principale del tuo sito, puoi impostarlo su "/" per aprirlo all'avvio dell'app. Se non fornisci un URL di avvio, il browser può utilizzare come inizio l'URL da cui è stata installata la PWA. Può trattarsi di un link diretto, ad esempio i dettagli di un prodotto anziché la schermata Home.
display
Una delle seguenti opzioni: fullscreen, standalone, minimal-ui o browser, che descrive in che modo il sistema operativo deve tracciare 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 sulla stessa origine. Se non viene impostato, start_url verrà utilizzato come valore di riserva. Tieni presente che, modificando start_url in futuro (ad esempio quando modifichi il valore della stringa di query), potresti impedire al browser di rilevare che una PWA è già installata.
di Gemini Advanced.
. di Gemini Advanced.

Icone

L'icona della PWA è la sua identità visiva in tutti gli utenti dispositivi quando sono installati, quindi è importante definirne almeno uno. Poiché la proprietà icons è una raccolta di oggetti icona, puoi definire varie icone in formati diversi per offrire agli utenti la migliore esperienza possibile d'uso delle icone. 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 se le icone non sono nelle dimensioni consigliate, su alcune piattaforme i criteri di installazione non vengono superati. 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 forme e dimensioni diverse. Ad esempio, su Android 12, diversi produttori o impostazioni possono modificare la forma delle icone da cerchi a quadrati a quadrati con angoli arrotondati. Per supportare questi tipi di icone adattive, puoi fornire un'icona mascherabile utilizzando il campo purpose.

Per farlo, fornisci un file immagine quadrato la cui icona principale sia 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 con un raggio del 40% all&#39;interno dell&#39;icona quadrata

Ecco un esempio di icona mascherabile visualizzata in varie forme di uso comune:

Nell'immagine seguente, se utilizzi l'icona a sinistra come icona mascherabile, i risultati sui dispositivi potrebbero essere scarsi quando viene applicata una maschera di forma.

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

Questa immagine potrebbe essere resa utilizzabile con una maggiore spaziatura interna.

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

Le icone mascherabili devono essere di almeno 512 x 512. Una volta creata, puoi aggiungerla alla tua raccolta icons per migliorare l'esperienza sui 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 ulteriore spaziatura interna. Maskable.app è uno strumento online senza costi per testare e creare una versione mascherabile della tua icona.

Il prossimo insieme di campi da includere è quello che migliorerà l'esperienza dell'utente, anche se non sono obbligatori per l'installazione.

theme_color
Colore predefinito dell'applicazione, che a volte influenza la modalità di visualizzazione del sito nel 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 segnaposto da visualizzare nello sfondo dell'applicazione prima che il relativo foglio di stile venga caricato. Safari su iOS, iPadOS e la maggior parte dei browser desktop attualmente ignorano questo campo.
scope
Modifica l'ambito di navigazione della PWA, per consentirti 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 colori con nome CSS, come salmon o orange, colori RGB come #FF5500 o funzioni colore senza trasparenza, come rgb() o hsl(). Per ulteriori informazioni, consulta il capitolo Design 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 iniziale.

Quando installi una PWA su Android, il dispositivo genera una schermata iniziale con le informazioni provenienti dal file manifest, come illustrato nel diagramma seguente.

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

Safari su iOS e iPadOS, d'altra parte, non utilizza il file manifest dell'app web per generare schermate iniziali. Utilizzano invece un'immagine collegata da un elemento <link> proprietario simile al modo in cui gestiscono le icone. Per ulteriori dettagli, consulta il capitolo Miglioramenti.

Campi estesi

La serie di campi successiva offre informazioni aggiuntive sulla PWA. Sono tutti facoltativi.

lang
Un tag lingua che specifica la lingua principale dei valori del file manifest, ad esempio en per l'inglese, pt-BR per il portoghese brasiliano o in per l'hindi.
dir
La direzione in cui visualizzare i campi manifest che supportano le indicazioni stradali (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 vengono inclusi, generalmente sono portrait o landscape esplicitamente.
di Gemini Advanced.
.

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 (simili all'oggetto icons) destinato a mostrare la PWA. Non ci sono limiti di dimensioni.
categories
Array di categorie a cui la PWA deve appartenere da utilizzare come suggerimenti per le schede, facoltativamente dall'elenco di categorie note. Questi valori sono generalmente minuscoli.
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.
di Gemini Advanced.
.

Puoi vedere questi campi promozionali in azione oggi stesso. Su Android, ad esempio, 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 "Aggiungi alla schermata Home" barra delle informazioni, in una finestra di dialogo di installazione più completa, simile a quella di uno store.

Su Android, l'UI di installazione può essere migliorata se specifichi dei valori per i campi promozionali, come vedrai nel prossimo video.

Guarda questi campi promozionali in azione:

Campi delle funzionalità

Infine, ci sono una serie di campi relativi a diverse funzionalità che la PWA può utilizzare nei browser supportati, ad esempio i campi shortcuts, share_target e display_overrides, come trattati nel capitolo Funzionalità. Sono inoltre disponibili campi, come related_apps e prefer_related_apps (vedi il capitolo Rilevamento per maggiori informazioni), per connettere la PWA alle app installate, spesso da uno store.

Molti nuovi campi potrebbero essere visualizzati in futuro mentre i browser aggiungono ulteriori funzionalità alle app web progressive.

Risorse