web app-manifest
en JSON-fil som beskriver et nettsted som installerbar app
Hva det er
Et web app-manifest, i bestemt form web app-manifestet og i daglig tale bare manifestet, er et
JSON-dokument som beskriver et nettsted som et program: hva det heter, hvilken adresse det åpnes på,
hvilke adresser som hører til det, hvordan vinduet skal se ut, og hvilke bilder som representerer
det. En side peker på filen med et link-element der rel er manifest, og en nettleser som
tilbyr installasjon, leser filen for å avgjøre hva den installerte kopien skal bli. Spesifikasjonen
fra W3C som definerer formatet, kaller det også bare manifestet.
Filen er ren JSON. Den registrerte medietypen er application/manifest+json og den registrerte
filendelsen .webmanifest, selv om spesifikasjonen godtar enhver JSON-medietype og mange nettsteder
serverer en manifest.json. Hvert medlem er valgfritt. Et lite manifest for et oppdiktet nettsted
med tidevannstabeller ser slik ut:
{
"name": "Harbour Tide Tables",
"short_name": "Tides",
"start_url": "/tides/",
"display": "standalone",
"background_color": "#ffffff",
"icons": [
{
"src": "/icons/tides-512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}Tre medlemmer avgjør hva appen er, til forskjell fra hvordan den ser ut. start_url foreslår siden den
installerte appen åpnes på; nettleseren kan ignorere den eller la brukeren endre den. scope er mengden adresser som regnes som en del av appen; mangler den,
tar spesifikasjonen start-URL-en og skjærer bort filnavn, spørrestreng og fragment, så eksempelet
over eier alt under /tides/. id er identiteten til appen, og mangler den, faller den tilbake på
start-URL-en. Relative ikonadresser og start-URL-en tolkes i forhold til URL-en til selve manifestet og ikke mot
siden som lenket til det. En relativ id tolkes derimot i forhold til start-URL-ens opprinnelse.
Resten er presentasjon. display ber om fullscreen, standalone, minimal-ui eller browser,
og en nettleser som ikke kan innfri ønsket, går nedover den listen i rekkefølge. Hvert ikon kan ha
et purpose: any som standard, maskable for et bilde som er tegnet for å tåle beskjæring, eller
monochrome for et bilde der fargen kastes og bare alfakanalen brukes. theme_color farger vinduet
rundt appen. Et tilhørende notat fra W3C legger til description, categories og screenshots,
som installasjonsdialoger og appbutikker kan vise.
Hvorfor det er viktig
Manifestet leverer installasjonsmetadata som nettstedet selv styrer. Spesifikasjonen overlater beslutningen om å installere til nettleseren: den kan tilby en måte å installere på, og hver nettleser setter sine egne betingelser, der noen krever bestemte medlemmer. Et team leverer inndataene, og nettleseren avgjør hva den gjør med dem. Det nyttige spørsmålet er derfor mindre om nettstedet skal ha et manifest, og mer hva manifestet lover.
Identiteten er løftet som lever lenger enn filen. Når en nettleser henter manifestet på nytt,
sier spesifikasjonen at den bør bruke en samsvarende id som et signal om at den nye filen
erstatter manifestet til en app som allerede er installert. Fordi en manglende id er det
samme som start-URL-en, endrer en flytting av startsiden identiteten i det stille. Nettleseren
bør derfor behandle den nye filen som en annen app enn den som ligger på leserens enhet.
Å låse id i den første utgivelsen koster én linje og fjerner den risikoen.
Omfanget avgjør hvor appvinduet slutter. Navigasjon innenfor scope blir i det installerte vinduet.
En lenke som går ut av det, åpnes fortsatt, men spesifikasjonen forventer at nettleseren viser
leseren at vedkommende er utenfor appen, så et omfang som er smalere enn nettstedet, får vanlige
lenker mellom seksjonene til å se ut som utganger.
Ikonene er der det meste av den synlige skaden skjer. Startmenyer og hjemskjermer beskjærer ikoner til sirkler, avrundede kvadrater og andre former, og en logo som fyller hele kvadratet sitt, mister kantene. Spesifikasjonen definerer den trygge sonen for et maskerbart ikon som en sirkel i midten med en radius på to femtedeler av ikonets korteste side, og alt utenfor den kan bli skåret bort. Et monokromt ikon beholder bare alfakanalen, så et ikon tegnet på en ugjennomsiktig bakgrunn blir til et ensfarget kvadrat.
Fargemedlemmene har et snevrere bruksområde enn det kan virke som. background_color er bare ment for øyeblikket før
stilarket kommer, og spesifikasjonen forbyr nettleseren å bruke den når stilarket er tilgjengelig.
Det er fargen ved den første opptegningen, og bare da.
Slik ser det ut i praksis
Dette nettstedet bygger manifestet fra en mal i stedet for å vedlikeholde en fil for hånd.
Hugo-konfigurasjonen registrerer application/manifest+json med endelsen webmanifest og gjør
manifestet til et utdataformat for hjemmesiden på hvert språk, så hvert språk får sin egen fil, og
hodet på hver side lenker til filen for sitt eget språk. Konfigurasjonen skriver ned hvorfor: én
felles kopi kan bare angi én start-URL, og en dansk besøkende som installerte nettstedet, fikk en
app som åpnet den engelske hjemmesiden.
Malen setter sammen manifestet som en nøkkel-verdi-struktur og gir den til JSON-koderen i Hugo, så escaping og
kommaer er koderens problem, og et manglende komma kan ikke sendes ut. Hver ikonadresse starter ved
roten av verten. Kommentaren i malen forklarer grunnen: en relativ adresse i
/da/manifest.webmanifest ville blitt tolket som en adresse under /da/, og hvert ikon på dansk ville gitt 404.
Selve ikonene leses fra disk i tre mapper, én per formål, med ti størrelser hver fra 36 til 512
piksler, og størrelsen hentes fra filnavnet, så en størrelse som generatoren legger til, dukker opp
i manifestet uten at noe må redigeres.
id er låst til hjemmeadressen for språket, og scope er hele opprinnelsen, så en lenke til et
annet språk blir i det installerte vinduet. Skjermbildene heter <lang>-<form_factor>-<WxH>.webp,
og malen leser alle tre opplysningene fra filnavnet: engelsk og dansk har hver ett bredt bilde på
1280 ganger 800 og ett smalt på 780 ganger 1688. Et språk uten skjermbilder får ikke noe
screenshots-medlem i det hele tatt, heller enn en tom liste.
Kolofonsiden lister spesifikasjonen fra W3C blant standardene nettstedet følger, og PWABuilder blant de eksterne sjekkene hvem som helst kan kjøre: en tjeneste som leser manifestet og resten av det som gjør nettstedet installerbart, fra Microsofts maskiner.
Installasjonssiden er leserens halvdel av den samme filen. Den viser hvor hver nettleser gjemmer installasjonskommandoen, og nevner at Apples nettlesere aldri tilbyr installasjon av seg selv. Firefox har en egen funksjon for nettappvinduer, aktivert som standard på Windows fra versjon 143, eller versjon 150 ved installasjon fra Microsoft Store. Mozillas implementasjonsdokumentasjon oppgir at Linux-støtten er deaktivert som standard, og at macOS-støtte ikke er tilgjengelig. Siden forteller også hva leseren kan forvente av dette nettstedet: den installerte appen er et ikon og et eget vindu. Nettstedet publiserer ingen service worker eller administrert frakoblet kopi, så det trenger en tilkobling ved normal bruk.
Hvor det går galt
Hvert ikon gir 404 på en oversatt sti. En relativ src tolkes i forhold til URL-en til manifestet, så
et manifest som serveres under et språkprefiks, ber om ikoner under det prefikset. Skriv
ikonadresser fra roten av verten, eller som fullstendige URL-er.
Den installerte appen åpnes på feil språk. Ett manifest kan angi én start-URL, så hver leser
installerer den samme hjemmesiden. Lever ett manifest per språk, hvert med sin egen start_url og
id, og lenk til det som passer, fra hver side.
Installerte kopier overser det nye manifestet. Uten id er identiteten start-URL-en, så å
flytte startsiden gir filen en ny identitet, og nettleseren bør behandle den som en annen app enn den leserne
allerede har. Sett id før den første utgivelsen, og la den være i fred etterpå.
Startmenyen beskjærer logoen. Et ikon med formålet any plasseres eller skjæres til slik
plattformen finner det best. Legg til et maskable-ikon med alt som betyr noe, innenfor sirkelen i
midten, der radien er 40 % av ikonets korteste side.
Endringer i manifestet endrer ingenting. HTML-standarden bruker bare det første link-elementet
der rel inneholder manifest, så når et tema eller et tillegg har lagt inn sin egen lenke
tidligere på siden, er filen som redigeres, aldri den som leses. Hold deg til nøyaktig én
manifestlenke per side.
Les mer
- Web Application Manifest — hvert medlem, hvordan en
nettleser behandler filen, og reglene for
id,scopeog formålet med ikoner. - Web App Manifest - Application Information —
description,categoriesogscreenshots, med formfaktorer og etiketter. - IANA: application/manifest+json
— registreringen av medietypen og filendelsen
.webmanifest. - HTML Standard: link type manifest — hvordan manifestlenken hentes, og hvorfor bare den første teller.
- Use web apps in Firefox for Windows — Windows-funksjonen og tilgjengeligheten fra versjon 143 eller Microsoft Store-versjon 150.
- Firefox Source Docs: Web Apps in Firefox — den gjeldende implementasjonen: Windows aktivert som standard, Linux deaktivert som standard og macOS ikke støttet.