Web app manifest

Cosa verifica questo controllo

Cerca <link rel="manifest" href="..."> nell’head del documento, recupera il file JSON riferito e valida che si parsi e contenga i campi che i browser richiedono per mostrare un prompt di installazione: name (o short_name), start_url, icons con almeno una 192×192 e una 512×512, e display.

Perché è importante

Il manifest controlla come il sistema operativo tratta il tuo sito una volta che un utente lo aggiunge alla schermata home.

• Android (Chrome, Samsung Internet, Edge): con un manifest valido più un service worker, il browser mostra il prompt “Aggiungi alla schermata home”. Senza, nessun banner di installazione — gli utenti devono trovare l’opzione nascosta nel menu.
• Chromebook / Chrome desktop / Edge: installabile come app standalone dall’icona omnibox della barra degli indirizzi.
• iOS Safari: legge name, theme_color e apple-touch-icon (ancora un link separato). Non rispetta display: standalone dal manifest — ti serve anche <meta name="apple-mobile-web-app-capable" content="yes">.
• Tab strip: Chrome usa theme_color dal meta tag e dal manifest (e dal corrispondente meta tag) per il colore di sfondo della barra degli indirizzi.

Anche se non vuoi un prompt di installazione PWA, il manifest alimenta comunque la favicon usata da Android quando gli utenti aggiungono un segnalibro, e l’icona che Chrome mostra nel menu di overflow delle tab su mobile.

Come sistemarlo

1. Collega il manifest da ogni pagina:

<link rel="manifest" href="/manifest.webmanifest" />
<meta name="theme-color" content="#0b0b0b" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />

L’estensione del file è convenzionalmente .webmanifest, ma .json funziona anche fintanto che la risposta è servita con Content-Type: application/manifest+json (o application/json).

2. Scrivi un manifest minimale valido:

{
  "name": "MetricSpot",
  "short_name": "MetricSpot",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0b0b0b",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

L’icona maskable è quella che Android usa per il badge della home screen. Senza, Android ritaglia la tua icona e ottieni un cerchio di spazio bianco attorno a un logo. Testa con maskable.app.

3. Servi il content type corretto:

location = /manifest.webmanifest {
  default_type application/manifest+json;
  add_header Cache-Control "public, max-age=3600";
}

Se il tuo host lo serve come text/plain o text/html, Chrome ignora il file silenziosamente.

Astro: metti manifest.webmanifest in public/ — Astro lo copia alla root del sito invariato. Aggiungi il <link> al tuo layout base.

Next.js (App Router): esporta un manifest tipizzato da app/manifest.ts e Next emette il JSON al momento della build:

// app/manifest.ts
import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
  return {
    name: "MetricSpot",
    short_name: "MetricSpot",
    start_url: "/",
    display: "standalone",
    background_color: "#ffffff",
    theme_color: "#0b0b0b",
    icons: [
      { src: "/icons/icon-192.png", sizes: "192x192", type: "image/png" },
      { src: "/icons/icon-512.png", sizes: "512x512", type: "image/png" },
    ],
  };
}

Il <link rel="manifest"> viene iniettato automaticamente da Next quando esiste questo file.

WordPress: il path più semplice è un plugin PWA (PWA by 10up, o Super Progressive Web Apps). O scrivi il manifest da solo, mettilo nella root del tema e aggiungi il tag <link> tramite wp_head:

add_action('wp_head', function () {
  echo '<link rel="manifest" href="' . esc_url(get_template_directory_uri() . '/manifest.webmanifest') . '">';
});

4. Abbinalo ai meta tag giusti. Il manifest fa la maggior parte del lavoro, ma iOS Safari e i crawler legacy vogliono ancora i tag separati:

<meta name="theme-color" content="#0b0b0b" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />

Vedi anche Apple touch icon e Favicon per il resto del set di icone.

Domande frequenti

Mi serve un service worker per passare questo controllo?

No. Il controllo del manifest verifica solo il <link> e il file JSON. Ti serve un service worker per essere installabile come PWA su Android — senza, il prompt di installazione non si mostrerà nemmeno con un manifest perfetto. Il manifest da solo ti dà comunque un’icona migliore per la home screen e i metadati per la tab strip.

Perché il mio prompt di installazione non si mostra su Android?

Tre cose sono richieste: un manifest valido con icone 192×192 e 512×512, un service worker che gestisce eventi fetch e il sito servito su HTTPS. Controlla chrome://inspect → “Devices” → la tua tab → Application → Manifest in DevTools — Chrome elenca esattamente quali criteri di installazione mancano.

Qual è la differenza tra display: standalone e display: fullscreen?

standalone nasconde il chrome del browser ma mantiene la status bar del sistema operativo (notifiche, ora, batteria) — quello che la maggior parte delle app vuole. fullscreen nasconde tutto ed è di solito appropriato solo per i giochi. minimal-ui mantiene una barra browser sottile con avanti/indietro; raramente usata. La maggior parte delle app installabili vuole standalone.