Web app-manifest
en JSON-fil, der beskriver et site som en installerbar app
Hvad det er
Et web app-manifest er et JSON-dokument, der beskriver et website som et
program: hvad det hedder, hvilken adresse det åbner på, hvilke adresser der
hører til det, hvordan vinduet skal se ud, og hvilke billeder der står for det.
Siden peger på filen med et link-element, hvis rel er manifest, og en
browser, der tilbyder installation, læser web app-manifestet for at afgøre, hvad
den installerede kopi skal være. W3C-specifikationen bag formatet kalder det
blot manifestet, og det gør de fleste i daglig tale også.
Filen er almindelig JSON. Den registrerede medietype er
application/manifest+json, og den registrerede filendelse er .webmanifest,
men specifikationen godtager enhver JSON-medietype, og mange sites serverer en
manifest.json. Alle medlemmer er valgfrie. Et lille manifest til et opdigtet
site med tidevandstabeller for en havn kan se sådan ud:
{
"name": "Havnens tidevandstabeller",
"short_name": "Tidevand",
"start_url": "/tidevand/",
"display": "standalone",
"background_color": "#ffffff",
"icons": [
{
"src": "/ikoner/tidevand-512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}Tre medlemmer bestemmer, hvad appen er, til forskel fra hvordan den ser ud.
start_url foreslår den side, den installerede app åbner på; browseren kan
ignorere den eller lade brugeren ændre den. scope er de adresser,
der regnes for at høre til inde i appen; mangler det, tager specifikationen
start-URL’en og skærer filnavn, forespørgsel og fragment af, så eksemplet
ovenfor ejer alt under /tidevand/. id er appens identitet, og mangler det,
falder det tilbage på start-URL’en. Relative ikonadresser og
start-URL’en fortolkes i forhold til manifestets egen URL og ikke til den side,
der linkede til det. Et relativt id fortolkes derimod i forhold til
start-URL’ens origin.
Resten handler om udseende. display beder om fullscreen, standalone,
minimal-ui eller browser, og en browser, der ikke kan imødekomme ønsket, går
ned ad listen i netop den rækkefølge. Hvert ikon kan have et purpose: any
som standard, maskable til et billede tegnet til at tåle beskæring eller
monochrome til et billede, hvis farver smides væk, så kun alfakanalen bruges.
theme_color farver vinduet omkring appen. En ledsagende W3C-note tilføjer
description, categories og screenshots, som installationsdialoger og
appbutikker kan vise.
Hvorfor det betyder noget
Manifestet leverer installationsmetadata, som sitet selv styrer. Specifikationen overlader beslutningen til browseren: den må tilbyde installation, og hver browser fastsætter sine egne betingelser, hvoraf nogle kræver bestemte medlemmer. Et team leverer råmaterialet, og browseren afgør, hvad der sker med det, så det nyttige spørgsmål handler mindre om, hvorvidt der skal være et manifest, end om, hvad det lover.
Identiteten er det løfte, der lever længere end filen. Når en browser henter
manifestet igen, siger specifikationen, at den bør bruge et matchende id som
tegn på, at den nye fil erstatter manifestet til en allerede installeret app.
Fordi et manglende id er lig med start-URL’en, skifter identiteten i stilhed,
når startsiden flyttes, så browseren bør behandle den nye fil som et andet
program end det, der ligger på læserens enhed. At låse id fast i den første
udgivelse koster én linje og fjerner den risiko.
Omfanget afgør, hvor appvinduet slutter. Navigation inden for scope bliver i
det installerede vindue. Et link, der fører ud, åbner stadig, men
specifikationen forventer, at browseren gør det synligt for læseren, at siden
ligger uden for appen, så et omfang, der er smallere end sitet, får almindelige
links mellem dets afsnit til at ligne udgange.
Ikonerne er dér, hvor det meste af den synlige skade sker. Hjemmeskærme og appstartere beskærer ikoner til cirkler, afrundede firkanter og andre former, og et logo, der fylder hele sit kvadrat, mister kanterne. Specifikationen definerer sikkerhedszonen for et maskable ikon som en cirkel i midten med en radius på to femtedele af ikonets korteste side, og alt uden for den kan blive skåret væk. Et monokromt ikon beholder kun sin alfakanal, så et ikon tegnet på en uigennemsigtig baggrund bliver til en massiv firkant.
Farvemedlemmerne rækker kortere, end de ser ud til. background_color er kun
ment til øjeblikket, før stylesheetet når frem, og specifikationen forbyder
browseren at bruge den, når stylesheetet er klar. Den farver det første billede,
og intet efter det.
Sådan ser det ud i praksis
Dette site bygger sit manifest ud fra en skabelon i stedet for at vedligeholde
en fil i hånden. Hugo-konfigurationen registrerer application/manifest+json
med endelsen webmanifest og gør manifestet til et output af hvert sprogs
forside, så hvert sprog får sin egen fil, og hovedet på hver side linker til
filen for sit eget sprog. Konfigurationen noterer også hvorfor: én fælles kopi
kan kun angive én start-URL, og en dansk besøgende, der installerede sitet, fik
en app, der åbnede den engelske forside.
Skabelonen samler manifestet med Hugos dict og sender det gennem Hugos
JSON-encoder, så escaping og kommaer er encoderens ansvar, og et glemt komma når
aldrig ud. Hver ikonadresse starter ved roden af værten, og kommentaren i
skabelonen forklarer grunden: en relativ adresse i /da/manifest.webmanifest
ville blive fortolket som en adresse under /da/, og hvert ikon på dansk ville give 404. Selve
ikonerne læses fra disken i tre mapper, én pr. formål, med ti størrelser i hver
fra 36 til 512 pixel, og størrelsen aflæses i filnavnet, så en størrelse, som
generatoren tilføjer, dukker op i manifestet, uden at nogen skal rette i det.
id er låst fast til sprogets forsideadresse, og scope er hele originet, så
et link over i et andet sprog bliver i det installerede vindue. Skærmbilleder
navngives <lang>-<form_factor>-<WxH>.webp, og skabelonen aflæser alle tre
oplysninger i filnavnet: engelsk og dansk har hver ét bredt billede på 1.280
gange 800 og ét smalt på 780 gange 1.688. Et sprog uden skærmbilleder får slet
intet screenshots-medlem, i stedet for en tom liste.
Kolofonen nævner W3C-specifikationen blandt de standarder, sitet følger, og PWABuilder blandt de eksterne tjek, enhver selv kan køre: en tjeneste på Microsofts servere, der gennemgår manifestet og alt det øvrige, som installation afhænger af.
Installationssiden er læserens halvdel af den samme fil. Den viser, hvor hver browser gemmer installationskommandoen, og fortæller, at Apples browsere aldrig tilbyder installation af sig selv. Firefox har en særskilt funktion til webappvinduer, som er slået til som standard på Windows fra version 143, eller version 150 hvis Firefox er installeret fra Microsoft Store. Mozillas implementeringsdokumentation angiver, at Linux-understøttelsen er slået fra som standard, og at macOS ikke understøttes. Siden afstemmer også forventningerne til dette site: den installerede app er et ikon og et selvstændigt vindue. Sitet udgiver ingen service worker eller administreret kopi til offlinebrug, så det kræver forbindelse til normal brug.
Hvor det går galt
Alle ikoner giver 404 på en oversat sti. En relativ src fortolkes i forhold
til manifestets URL, så et manifest, der serveres under et sprogpræfiks, beder
om ikoner under samme præfiks. Skriv ikonadresser fra værtens rod eller som
fulde URL’er.
Den installerede app åbner på det forkerte sprog. Ét manifest kan angive én
start-URL, så alle læsere installerer den samme forside. Server ét manifest pr.
sprog med sin egen start_url og sit eget id, og link til det passende fra
hver side.
Installerede kopier overser det nye manifest. Uden id er identiteten
start-URL’en, så når startsiden flyttes, får filen en ny identitet, og browseren
bør derefter behandle den som en anden app end den, læserne allerede har. Sæt id før første
udgivelse, og lad det ligge bagefter.
Hjemmeskærmen beskærer logoet. Et ikon med formålet any placeres eller
beskæres, som platformen finder passende. Tilføj et maskable ikon, hvor alt
vigtigt ligger inden for den midterste cirkel, hvis radius er 40 % af ikonets
korteste side.
Rettelser i manifestet gør ingen forskel. HTML-standarden bruger kun det
første link-element, hvis rel indeholder manifest, så har et tema eller et
plugin sat sit eget link tidligere på siden, bliver den fil, der rettes i,
aldrig læst. Hold præcis ét manifestlink pr. side.
Læs mere
- Web Application Manifest — alle
medlemmer, hvordan en browser behandler filen, og reglerne for
id,scopeog ikonformål. - Web App Manifest - Application Information
—
description,categoriesogscreenshotsmed formfaktorer og etiketter. - IANA: application/manifest+json
— registreringen af medietypen og filendelsen
.webmanifest. - HTML Standard: link type manifest — hvordan manifestlinket hentes, og hvorfor kun det første tæller.
- Use web apps in Firefox for Windows — Windows-funktionen og dens tilgængelighed fra version 143 eller Microsoft Store-version 150.
- Firefox Source Docs: Web Apps in Firefox — den aktuelle implementering: Windows slået til som standard, Linux slået fra som standard og macOS ikke understøttet.