# Web-App-Manifest

## Was es ist

Ein Web-App-Manifest ist ein JSON-Dokument, das eine Website als Anwendung
beschreibt: ihren Namen, ihre Startadresse, die zugehörigen Adressen, das Aussehen
ihres Fensters und die Bilder, die sie repräsentieren. Eine Seite verweist mit
einem `link`-Element und `rel` gleich `manifest` auf die Datei. Ein Browser, der
eine Installation anbietet, liest daraus, welche Eigenschaften die installierte
Fassung haben soll. Die W3C-Spezifikation nennt es schlicht Manifest, ebenso wie der übliche
Sprachgebrauch.

Die Datei ist gewöhnliches JSON. Ihr registrierter Medientyp ist
`application/manifest+json`, ihre registrierte Endung `.webmanifest`. Die
Spezifikation akzeptiert jedoch jeden JSON-Medientyp, und viele Websites liefern
eine `manifest.json` aus. Alle Einträge sind optional. Ein kleines Manifest für
eine erfundene Website mit Gezeitentabellen sieht so aus:

```json
{
    "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"
        }
    ]
}
```

Drei Einträge bestimmen, was die App ist, im Unterschied zu ihrem Aussehen.
`start_url` schlägt die Seite vor, mit der die installierte App startet. Der Browser
kann sie ignorieren oder dem Nutzer erlauben, sie zu ändern. `scope` ist die Menge
der Adressen innerhalb der App. Fehlt dieser Eintrag, verwendet die Spezifikation
die Start-URL ohne Dateinamen, Abfrage und Fragment. Im Beispiel gehört damit alles
unter `/tides/` zur App. `id` ist ihre Identität und fällt, wenn es fehlt, auf die
Start-URL zurück. Relative Iconadressen und die Start-URL werden relativ zur URL
des Manifests aufgelöst, nicht zu der Seite, die es verlinkt. Eine relative `id`
bezieht sich dagegen auf die Origin der Start-URL.

Die übrigen Einträge betreffen die Darstellung. `display` fordert `fullscreen`,
`standalone`, `minimal-ui` oder `browser` an. Kann ein Browser die gewünschte
Darstellung nicht umsetzen, geht er diese Liste in der angegebenen Reihenfolge
weiter. Jedes Icon kann einen `purpose` haben: standardmäßig `any`, `maskable` für
ein Bild, das einen Beschnitt verträgt, oder `monochrome` für eines, dessen Farbe
verworfen und nur dessen Alphakanal verwendet wird. `theme_color` färbt den
Fensterrahmen der App. Eine ergänzende W3C-Note beschreibt `description`,
`categories` und `screenshots`, die Installationsdialoge und App-Stores anzeigen
können.

## Warum es wichtig ist

Das Manifest liefert Installationsmetadaten unter der Kontrolle der Website.
Die Spezifikation überlässt die Installationsentscheidung dem Browser: Er kann
einen Installationsweg anbieten und legt seine Bedingungen selbst fest. Einige
davon verlangen bestimmte Einträge. Das Team liefert die Eingabe, der Browser
entscheidet über ihre Verwendung. Die nützliche Frage ist daher weniger, ob ein
Manifest nötig ist, sondern was es verspricht.

Die Identität ist das Versprechen, das die Datei überdauert. Ruft ein Browser
das Manifest erneut ab, soll er laut Spezifikation eine übereinstimmende `id` als
Hinweis verstehen, dass die neue Datei das Manifest einer bereits installierten
App ersetzt. Ohne `id` ist die Start-URL die Identität. Wird die Startseite
verschoben, ändert sich diese stillschweigend, und der Browser soll die neue Datei
als andere Anwendung behandeln als die auf dem Gerät des Lesers. Eine feste `id`
ab der ersten Veröffentlichung kostet eine Zeile und beseitigt dieses Risiko.

Der Geltungsbereich bestimmt, wo das App-Fenster endet. Navigation innerhalb
dieses Bereichs bleibt im installierten Fenster. Ein Link nach außerhalb öffnet
sich weiterhin, doch die Spezifikation erwartet, dass der Browser den Wechsel aus
der App kenntlich macht. Ein engerer Bereich als die Website lässt damit normale
Links zwischen ihren Abschnitten wie Ausgänge wirken.

Bei Icons entstehen die meisten sichtbaren Schäden. Startoberflächen schneiden
sie zu Kreisen, abgerundeten Quadraten und anderen Formen zu. Ein Logo, das sein
ganzes Quadrat ausfüllt, verliert dabei die Ränder. Für ein maskierbares Icon
definiert die Spezifikation die sichere Zone als mittigen Kreis mit einem Radius
von zwei Fünfteln der kürzeren Iconseite. Alles außerhalb darf abgeschnitten
werden. Ein monochromes Icon behält nur seinen Alphakanal. Ein Icon auf einem
undurchsichtigen Hintergrund wird dadurch zu einem ausgefüllten Quadrat.

Die Farbeinträge haben einen engeren Zweck, als es scheint. `background_color`
ist nur für den Moment gedacht, bevor das Stylesheet eintrifft. Die Spezifikation
verbietet dem Browser, den Wert zu verwenden, sobald das Stylesheet verfügbar ist.
Der Eintrag bestimmt nur die Hintergrundfarbe der ersten Darstellung.

## Wie es in der Praxis aussieht

Diese Website erzeugt ihr Manifest aus einer Vorlage, statt eine Datei von Hand
zu pflegen. Die Hugo-Konfiguration registriert `application/manifest+json` mit der
Endung `webmanifest` und legt das Manifest als Ausgabe der Startseite jeder
Sprache fest. So bekommt jede Sprache eine eigene Datei, und der Kopf jeder Seite
verlinkt die Datei ihrer Sprache. Die Konfiguration hält den Grund fest: Eine
globale Fassung kann nur eine Start-URL nennen. Ein Besucher, der die dänische Fassung der
Website installierte, bekam deshalb eine App mit der englischen Startseite.

Die Vorlage baut das Manifest als Zuordnung auf und übergibt sie Hugos
JSON-Kodierer. Escapezeichen und Kommas sind damit dessen Aufgabe; ein fehlendes
Komma kann nicht veröffentlicht werden. Jede Iconadresse beginnt an der Wurzel
des Hosts. Der Kommentar begründet das ausdrücklich: Eine relative Adresse in
`/da/manifest.webmanifest` würde unter `/da/` aufgelöst, und jedes Icon der dänischen
Fassung würde einen 404-Fehler liefern. Die Icons selbst werden aus drei Ordnern
im Dateisystem gelesen, einem pro Verwendungszweck, mit je zehn Größen von 36
bis 512 Pixeln. Die Größe stammt aus dem Dateinamen. Eine vom Generator ergänzte
Größe erscheint daher ohne weitere Änderung im Manifest.

`id` ist auf die Startadresse der jeweiligen Sprache festgelegt, `scope` umfasst
die gesamte Origin. Ein Link in eine andere Sprache bleibt somit im installierten
Fenster. Screenshots heißen `<lang>-<form_factor>-<WxH>.webp`. Die Vorlage liest
alle drei Angaben aus dem Dateinamen: Englisch und Dänisch haben jeweils eine
breite Aufnahme mit 1.280 mal 800 und eine schmale mit 780 mal 1.688 Pixeln. Bei einer
Sprache ohne Screenshots fehlt der Eintrag `screenshots` vollständig, statt eine
leere Liste zu enthalten.

Die [Credits-Seite](/de/credits/) führt die W3C-Spezifikation unter den Standards
der Website auf und PWABuilder unter den externen Prüfungen, die jeder ausführen
kann. Der Dienst liest von Microsofts Rechnern aus das Manifest und die übrigen
Bestandteile, die die Website installierbar machen.

Die [Installationsseite](/de/install/) erklärt dieselbe Datei aus Lesersicht.
Sie zeigt, wo die einzelnen Browser den Installationsbefehl anbieten, und weist
darauf hin, dass Apples Browser nie von sich aus dazu auffordern. Firefox bietet
ein separates Fenster für Web-Apps, unter Windows standardmäßig ab Version 143
beziehungsweise bei Installationen aus dem Microsoft Store ab Version 150.
Mozillas Implementierungsdokumentation nennt Linux-Unterstützung als standardmäßig
deaktiviert und macOS-Unterstützung als nicht verfügbar. Die Seite klärt auch,
was bei dieser Website zu erwarten ist: Die installierte App ist ein Icon und
ein eigenes Fenster. Die Website veröffentlicht weder einen Service Worker noch
eine verwaltete Offlinekopie. Für die normale Nutzung braucht sie daher eine
Verbindung.

## Wo es schiefgeht

**Alle Icons liefern unter übersetzten Pfaden 404.** Ein relatives `src` wird
relativ zur URL des Manifests aufgelöst. Ein Manifest unter einem Sprachpräfix
fordert Icons deshalb unter diesem Präfix an. Schreiben Sie Iconadressen von der
Wurzel des Hosts aus oder als vollständige URLs.

**Die installierte App startet in der falschen Sprache.** Ein Manifest kann
eine Start-URL angeben, also installieren alle Leser dieselbe Startseite. Liefern
Sie für jede Sprache ein eigenes Manifest mit eigener `start_url` und `id` aus
und verlinken Sie auf jeder Seite die passende Fassung.

**Installierte Fassungen ignorieren das neue Manifest.** Ohne `id` bestimmt die
Start-URL die Identität. Das Verschieben der Startseite gibt der Datei daher eine
neue Identität, und der Browser soll sie als andere App behandeln als die bereits
installierte. Legen Sie `id` vor der ersten Veröffentlichung fest und lassen Sie
den Wert danach unverändert.

**Die Startoberfläche beschneidet das Logo.** Ein Icon mit dem Zweck `any` wird
nach Ermessen der Plattform platziert oder zugeschnitten. Ergänzen Sie ein
`maskable`-Icon, bei dem alles Wichtige innerhalb des mittigen Kreises liegt,
dessen Radius 40 % der kürzeren Iconseite beträgt.

**Änderungen am Manifest bleiben ohne Wirkung.** Der HTML-Standard verwendet
nur das erste `link`-Element, dessen `rel` den Wert `manifest` enthält. Hat ein Theme
oder Plugin vorher einen eigenen Link eingefügt, wird die bearbeitete Datei gar
nicht gelesen. Belassen Sie auf jeder Seite genau einen Manifest-Link.

## Weiterführende Lektüre

- [Web Application Manifest](https://www.w3.org/TR/appmanifest/) — alle Einträge,
  ihre Verarbeitung durch den Browser und die Regeln für `id`, `scope` und
  Iconzwecke.
- [Web App Manifest - Application Information](https://www.w3.org/TR/manifest-app-info/)
  — `description`, `categories` und `screenshots` mit Formfaktoren und Beschriftungen.
- [IANA: application/manifest+json](https://www.iana.org/assignments/media-types/application/manifest+json)
  — Registrierung des Medientyps und der Endung `.webmanifest`.
- [HTML Standard: link type manifest](https://html.spec.whatwg.org/multipage/links.html#link-type-manifest)
  — Abruf des Manifest-Links und der Grund, warum nur der erste zählt.
- [Use web apps in Firefox for Windows](https://support.mozilla.org/en-US/kb/web-apps-firefox-windows)
  — die Windows-Funktion ab Version 143 beziehungsweise im Microsoft Store ab 150.
- [Firefox Source Docs: Web Apps in Firefox](https://firefox-source-docs.mozilla.org/browser/components/taskbartabs/docs/index.html)
  — die aktuelle Implementierung: unter Windows standardmäßig aktiviert, unter
  Linux standardmäßig deaktiviert, unter macOS nicht unterstützt.

<https://engineer.company/de/glossary/webmanifest/>
