Soms krijg ik vragen van klanten waarom hun web app er zo anders uitziet wanneer ze deze installeren op hun telefoon. De splash screen ziet er vreemd uit, de app opent in een browser-achtige weergave, of de iconen zijn wazig. Dit gebeurt wanneer het web app manifest niet correct is geconfigureerd. Het manifest bestand is het hart van elke progressive web app die zich gedraagt als een native applicatie.
Het web app manifest is een JSON-bestand dat browsers vertelt hoe jouw web applicatie moet worden weergegeven wanneer deze wordt geïnstalleerd. Zonder een goed manifest bestand zal jouw PWA nooit die native app-ervaring leveren die gebruikers verwachten. Browsers vallen terug op standaard instellingen die meestal teleurstellend zijn.
Basisstructuur van een manifest bestand
Het manifest bestand bevat essentiële metadata over jouw applicatie. Hier is een standaard configuratie die ik altijd als uitgangspunt neem:
{
"name": "Mijn Geweldige Web App",
"short_name": "MijnApp",
"description": "Een krachtige web applicatie voor dagelijkse taken",
"start_url": "/",
"scope": "/",
"display": "standalone",
"orientation": "portrait-primary",
"theme_color": "#2563eb",
"background_color": "#ffffff",
"lang": "nl-NL"
}
De name eigenschap wordt weergegeven bij de installatie prompt en in app stores. De short_name verschijnt onder het icoon op het startscherm waar ruimte beperkt is. Ik houd de korte naam altijd onder de 12 karakters om afkapping te voorkomen op de meeste apparaten.
Het start_url veld bepaalt welke pagina wordt geladen wanneer gebruikers jouw app openen vanaf hun startscherm. Vaak stel ik dit in op de hoofdpagina, maar voor specifieke workflows kan ik dit wijzigen naar een dashboard of landingspagina. De scope eigenschap definieert welke URL's binnen jouw applicatie vallen en welke naar de browser leiden.
Display modi en hun impact op gebruikerservaring
De display eigenschap is cruciaal voor hoe jouw app eruitziet. Er zijn vier hoofdmodi die elk een andere ervaring bieden. De standalone modus verbergt browser UI-elementen zoals de adresbalk en navigatieknoppen, waardoor jouw app eruitziet als een native applicatie.
{
"display": "standalone"
}
Voor apps die soms externe links openen, werk ik met minimal-ui. Deze modus toont een minimale set browser controls maar houdt de app-achtige ervaring. De fullscreen modus verbergt alle browser interface en is perfect voor games of media apps.
{
"display": "minimal-ui",
"display_override": ["standalone", "minimal-ui", "browser"]
}
Browser ondersteuning verschilt per platform. Android Chrome ondersteunt meer display modi dan Safari op iOS. Door display_override te specificeren, kan ik een voorkeursvolgorde aangeven. Als de eerste optie niet ondersteund wordt, probeert de browser de volgende.
Oriëntatie-instellingen bepalen hoe jouw app reageert op apparaat rotatie. Voor de meeste business apps stel ik portrait-primary in, maar voor games of media apps kan landscape beter werken:
{
"orientation": "any",
"orientations": ["portrait-primary", "landscape-primary"]
}
Iconen configureren voor verschillende apparaten
Het icoon systeem is waar veel ontwikkelaars de fout in gaan. Verschillende apparaten en browsers verwachten specifieke afmetingen. iOS heeft andere vereisten dan Android, en Windows weer andere.
{
"icons": [
{
"src": "/icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "/icons/icon-96x96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "/icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "/icons/icon-144x144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "/icons/icon-152x152.png",
"sizes": "152x152",
"type": "image/png"
},
{
"src": "/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Ik genereer altijd iconen in PNG formaat met transparante achtergrond. Het 192x192 icoon is het minimum voor Chrome's installatie prompt. Het 512x512 formaat wordt vaak gevraagd door app stores en splash screens. Maskable iconen zijn een nieuwere toevoeging die belangrijk wordt voor Android:
{
"src": "/icons/icon-192x192-maskable.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
}
Maskable iconen hebben extra padding omdat Android ze kan bijsnijden in verschillende vormen. Het purpose veld kan any, maskable of monochrome zijn. Voor de beste compatibiliteit maak ik meestal twee versies: een standaard icoon en een maskable variant.
Geavanceerde manifest eigenschappen
Moderne browsers ondersteunen geavanceerdere manifest eigenschappen die de gebruikerservaring verder verbeteren. De categories eigenschap helpt app stores jouw applicatie te categoriseren:
{
"categories": ["productivity", "business", "utilities"],
"iarc_rating_id": "e58c174a-81d2-5c3c-32cc-34b8de4a52e9"
}
Voor apps die specifieke protocollen of bestanden afhandelen, kan ik handlers definiëren:
{
"protocol_handlers": [
{
"protocol": "web+myapp",
"url": "/handle?protocol=%s"
}
],
"file_handlers": [
{
"action": "/upload",
"accept": {
"image/*": [".png", ".jpg", ".jpeg"]
}
}
]
}
Shortcuts in het manifest creëren snelle acties in het context menu wanneer gebruikers lang indrukken op jouw app icoon:
{
"shortcuts": [
{
"name": "Nieuw document",
"short_name": "Nieuw",
"description": "Maak een nieuw document aan",
"url": "/new",
"icons": [
{
"src": "/icons/new-document.png",
"sizes": "96x96"
}
]
},
{
"name": "Dashboard",
"url": "/dashboard",
"icons": [
{
"src": "/icons/dashboard.png",
"sizes": "96x96"
}
]
}
]
}
Implementatie en validatie
Het manifest bestand link ik in de HTML head sectie van mijn applicatie. Deze link moet op elke pagina staan die onderdeel is van de PWA:
<link rel="manifest" href="/manifest.json">
Chrome DevTools heeft een Application tab waar ik mijn manifest kan inspecteren. Hier zie ik direct of alle eigenschappen correct worden herkend en of iconen goed laden. Firefox heeft vergelijkbare tools in de Developer Tools onder het Storage tabblad.
Voor validatie draai ik vaak een lighthouse audit die specifiek PWA-aspecten controleert. Dit geeft concrete feedback over ontbrekende manifest eigenschappen of verkeerd geconfigureerde instellingen. PWA Builder van Microsoft heeft ook een handige manifest validator die veel voorkomende problemen detecteert.
Ik test altijd op echte apparaten hoe de installatie ervaring aanvoelt. Desktop Chrome toont een installatie banner in de adresbalk. Mobile browsers hebben verschillende installatie flows die ik allemaal doorloop. Safari op iOS heeft eigen merkwaardigheden met web app clips en het Apple touch icoon systeem.
Een goed geconfigureerd manifest bestand transformeert jouw web applicatie van een glorified bookmark naar een echte app-ervaring. Gebruikers merken het verschil direct in snelheid, visuele presentatie en het gevoel dat ze een native applicatie draaien. De tijd die ik investeer in het perfect krijgen van het manifest, betaalt zich altijd terug in hogere gebruikerstevredenheid.