Web app-manifest

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:

```json
{
    "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`, `scope` og ikonformål.

  * Web App Manifest - Application Information — `description`,
`categories` og `screenshots` med 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.

hDenne side på nettet	URL:https://engineer.company/da/glossary/webmanifest/	engineer.company	70
