back to top

Il file manifest.json: cos’è e a cosa serve

Il file manifest.json è un componente chiave nelle applicazioni web moderne, specialmente per le Progressive Web App (PWA).

Questo file, infatti, fornisce una serie di importanti informazioni sull’applicazione web che ne descrivono il comportamento e l’aspetto.

In questo articolo, esploreremo cos’è il file manifest.json, a cosa serve, come configurarlo e alcuni esempi pratici per aiutarti a integrarlo correttamente nella tua web application.

Cos’è il file manifest.json?

Il file manifest.json è un file di configurazione in formato JSON (JavaScript Object Notation) utilizzato principalmente nelle applicazioni web, in particolare nelle Progressive Web App.

Esso contiene metadati che descrivono l’applicazione, come il nome, le icone, i colori e altre informazioni che permettono al browser di trattare correttamente la PWA.

L’obiettivo principale del manifest.json è quello di migliorare l’esperienza utente, facilitando l’aggiunta dell’applicazione alla schermata principale di un dispositivo al fine di fornire un’esperienza d’uso simile a quella di un’app nativa.

Struttura del file manifest.json

Un file manifest.json è una semplice file di testo che contiene una serie di dati in formato JSON. Affinché il file sia valido deve essere formattato seguendo delle linee guida ben precise definite nelle specifiche.

Ogni proprietà inclusa nel file è opzionale, ma è consigliabile configurare almeno le proprietà essenziali per garantire un corretto funzionamento dell’applicazione. Ecco un esempio di base della struttura del file:

{
"name": "Nome Completo della tua App",
"short_name": "Nome Breve della tua App",
"description": "Una breve descrizione della tua applicazione",
"start_url": "/index.html",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#000000",
"icons": [
{
"src": "/img/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/img/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}

Le proprietà principali che è possibile includere in un file manifest.json sono le seguenti:

  • name: Il nome completo dell’applicazione, che apparirà quando l’utente installerà l’app.
  • short_name: Una versione abbreviata del nome che verrà utilizzata quando lo spazio è limitato, come nella schermata home di un dispositivo mobile.
  • description: Una breve descrizione dell’app che aiuta l’utente a capire lo scopo dell’applicazione che sta installando.
  • start_url: L’URL iniziale da caricare quando l’app viene aperta. Di solito è la homepage dell’applicazione. Può essere sia una URL assoluta che relativa.
  • display: Definisce come l’applicazione viene visualizzata. Le opzioni principali sono:
    • fullscreen: L’applicazione si apre a schermo intero senza barra del browser.
    • standalone: L’app si comporta come una normale app mobile, senza barra degli indirizzi.
    • minimal-ui: Mostra una barra con pulsanti di navigazione base.
    • browser: L’app si apre come una pagina web standard nel browser.
  • background_color: Il colore di sfondo della schermata di avvio dell’app.
  • theme_color: Il colore del tema dell’app, che influenzerà la barra superiore del browser sui dispositivi mobili.
  • icons: Un array di oggetti che specificano le icone utilizzate dall’app. Ogni oggetto include le seguenti proprietà:
    • src: Il percorso dell’icona.
    • sizes: Le dimensioni dell’icona, espresse come stringa (es. “192×192”).
    • type: Il tipo di immagine (es. “image/png”).

Qui sotto un esempio più completo di un file manifest.json con un maggior numero di proprietà per una maggiore personalizzazione:

{
  "name": "Mr.Webmaster App",
  "short_name": "MRW App",
  "description": "Una fantastica app che ti permette di avere MRW sempre con te!",
  "start_url": "/home",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#cc5200",
  "orientation": "portrait",
  "scope": "/",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "related_applications": [],
  "prefer_related_applications": false
}

Configurazione di un file manifest.json

La configurazione di un file manifest.json varia in base all’applicazione, ma ci sono alcuni passaggi comuni da seguire per configurarlo correttamente:

La prima cosa da fare è creare un file vuoto chiamato manifest.json e salvarlo nella root del progetto. Per creare un file json è sufficiente utilizzare un editor di testo (come il Blocco Note di Windows) avendo cura di salvare il file con estensione .json invece di .txt.

All’interno del nostro file manifest.json andiamo ad inserire le proprietà essenziali come namestart_urliconsdisplay, e theme_color. Per semplificare il lavoro potete fare copia e incolla del codice di esempio visto prima avendo cura, ovviamente, di personalizzarlo conn i dati della vostra app.

Una volta creato il file, questo dovrà essere “collegato” alla vostra applicazione. Per farlo sarà sufficiente inserire all’interno del codice HTML (nella porzione di codice tra <head> e </head>) un tag <link> come da esempio:

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

Per verificare di aver fatto tutto correttamente è consigliabile effettuare un test mediante strumenti come Lighthouse che consentono di verificare la corretta integrazione e il comportamento della PWA.

Strumenti utili per generare e validare manifest.json

Esistono diversi strumenti che facilitano la creazione e la validazione del file manifest.json. Vediamoli brevemente:

PWA Builder

Scopri l'universo dello sviluppo PWA con la nostra homepage che presenta un gatto astronauta, pronto a guidarti nell'avvio di una nuova PWA o nell'esplorazione degli strumenti per sviluppatori. Scopri cos'è una PWA e comprendi a cosa serve con approfondimenti sulla creazione del tuo file manifest.json.

Uno strumento online che ti permette di generare rapidamente il file manifest.json e altri componenti necessari per trasformare una web app in una PWA.

Web App Manifest Validator (by Redirection.io)

Screenshot di una pagina web intitolata "Web App Manifest Validator" con un modulo per immettere l'URL di un sito web per l'analisi, che spiega cos'è e l'importanza del file manifest.json per garantire il funzionamento impeccabile della tua app.

Un validatore online che verifica se il tuo file manifest.json segue le specifiche corrette. Basta inserire la URL della web application per verificare la correttezza dell’implementazione effettuata.

Lighthouse

E’ possibile verificare la corretta implementazione del file manifest.json anche mediante Lighthouse, un tool integrato in Chrome DevTools che ti aiuta a verificare le performance e la conformità della tua PWA, inclusa la corretta configurazione del manifest.json.

Domande Frequenti

È obbligatorio utilizzare il file manifest.json in una PWA?

No, ma è fortemente raccomandato se vuoi che la tua applicazione venga trattata come una PWA e offra una migliore esperienza utente sui dispositivi mobili.

Cosa succede se non specifico tutte le proprietà?

Il tuo file manifest.json sarà comunque valido, ma potresti non ottenere il comportamento desiderato. Ad esempio, senza un’icona specificata, la tua app potrebbe non avere un’icona appropriata quando aggiunta alla schermata principale.

Posso usare il manifest.json per applicazioni non-PWA?

Sì, alcune proprietà del manifest.json, come le icone, possono essere utili anche per applicazioni non-PWA, specialmente per migliorare l’aspetto e l’accessibilità su dispositivi mobili.

E’ sufficiente includere manifest.json per trasformare un sito web in una PWA?

No. Il manifest.json è solo uno dei requisiti necessari per rendere il sito una PWA, ma ci sono altri componenti essenziali da implementare. Un altro elemento essenziale è il service worker, un componente fondamentale per abilitare le funzionalità offline (cache) e altre capacità avanzate di una PWA.

Altri contenuti interessanti

Pubblicità
Massimiliano Bossi
Massimiliano Bossi
Stregato dalla rete sin dai tempi delle BBS e dei modem a 2.400 baud, ho avuto la fortuna di poter trasformare la mia passione in un lavoro (nonostante una Laurea in Giurisprudenza). Adoro scrivere codice e mi occupo quotidianamente di comunicazione, design e nuovi media digitali. Orgogliosamente "nerd" sono il fondatore di MRW.it (per il quale ho scritto centinaia di articoli) e di una nota Web-Agency (dove seguo in prima persona progetti digitali per numerosi clienti sia in Italia che all'estero).

Leggi anche...

Richiedere fattura per l’abbonamento all’Apple Developer Program

Gli sviluppatori italiani che vogliono pubblicare le proprie app...

Infinite scroll, come programmarlo su AMP e su Web con Javascript

L'infinite scroll è una tecnica di design e navigazione...

Codice Fiscale: 5 javascript per la verifica e il calcolo

Il codice fiscale è un identificativo tributario univoco che...

Flutter: framework multipiattaforma per lo sviluppo di app iOS e Android

Flutter è un progetto open source per la creazione...

Math.ceil() – Arrotondare per eccesso con Javascript

Il metodo ceil() dell'oggetto Math di Javascript è utilizzato...

AMP: cos’è e come funziona (Guida alle Accelerated Mobile Pages)

AMP (Accelerated Mobile Pages) è una tecnologia, o più...
Pubblicità