Web-App-Manifest

Das Web-App-Manifest ist eine von Ihnen erstellte Datei, die dem Browser mitteilt, wie Ihr Webinhalt im Betriebssystem als App angezeigt werden soll. Das Manifest kann grundlegende Informationen wie den Namen, das Symbol und die Designfarbe der App enthalten. erweiterte Einstellungen wie gewünschte Ausrichtung und App-Verknüpfungen und Katalogmetadaten wie Screenshots.

Jede PWA sollte pro Anwendung nur ein Manifest enthalten. Dieses wird normalerweise im Stammordner gehostet und ist auf allen HTML-Seiten verlinkt, über die die PWA installiert werden kann. Die offizielle Erweiterung lautet .webmanifest. Ein Name für das Manifest wäre also beispielsweise app.webmanifest.

Web-App-Manifest zur PWA hinzufügen

Um ein Web-App-Manifest zu erstellen, erstellen Sie zuerst eine Textdatei mit einem JSON-Objekt, das mindestens ein name-Feld mit einem Stringwert enthält:

app.webmanifest:

{
   "name": "My First Application"
}

Es reicht jedoch nicht aus, eine Datei zu erstellen. Auch der Browser muss wissen, dass sie existiert.

Mit deinem Manifest verknüpfen

Damit der Browser auf das Manifest Ihrer Web-App aufmerksam wird, müssen Sie es mit Ihrer PWA verknüpfen. Dazu verwenden Sie ein <link>-HTML-Element und das Attribut rel, das auf allen HTML-Seiten Ihrer PWA auf manifest gesetzt ist. Das funktioniert ähnlich wie das Verknüpfen eines CSS-Stylesheets mit einem Dokument.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

Manifest-Fehler beheben

Um sicherzustellen, dass das Manifest richtig eingerichtet ist, kannst du den Inspector in Firefox und die Entwicklertools in jedem Chromium-basierten Browser verwenden.

Für Chromium-Browser

In den Entwicklertools

  1. Wählen Sie im linken Bereich unter Application (Anwendung) Manifest aus.
  2. Prüfen Sie die Felder des Manifests, wie sie vom Browser geparst wurden.

Für Firefox

  1. Öffnen Sie den Inspector.
  2. Öffnen Sie den Tab „Anwendung“.
  3. Wählen Sie im linken Bereich die Option „Manifest“ aus.
  4. Prüfen Sie die Felder des Manifests, wie sie vom Browser geparst wurden.

Eine PWA gestalten

Ihre PWA ist jetzt mit ihrem Manifest verknüpft. Füllen Sie nun die restlichen Felder aus, um die Nutzererfahrung für Ihre Nutzer festzulegen.

Grundlegende Felder

Die erste Gruppe von Feldern enthält die wichtigsten Informationen zu Ihrer PWA. Sie werden verwendet, um das Symbol und das Fenster der installierten PWA zu erstellen und zu bestimmen, wie sie gestartet wird. Sie sind:

name
Vollständiger Name Ihrer PWA. Es wird zusammen mit dem Symbol auf dem Startbildschirm, im Launcher, im Dock oder im Menü des Betriebssystems angezeigt.
short_name
Optional, ein kürzerer Name Ihrer PWA, der verwendet wird, wenn nicht genügend Platz ist, um den vollständigen Wert des Felds name anzuzeigen. Er sollte nicht länger als 12 Zeichen sein, damit er nicht abgeschnitten wird.
icons
Array von Symbolobjekten mit src, type, sizes und optionalen purpose-Feldern, die beschreiben, welche Bilder die PWA darstellen sollen
start_url
Die URL, die die PWA laden soll, wenn der Nutzer sie über das installierte Symbol startet. Es wird ein absoluter Pfad empfohlen. Wenn die Startseite Ihrer PWA das Stammverzeichnis Ihrer Website ist, können Sie diesen Wert auf „/“ setzen. um sie beim Start der App zu öffnen. Wenn Sie keine Start-URL angeben, kann der Browser die URL verwenden, über die die PWA installiert wurde. Das kann ein Deeplink sein, z. B. die Details zu einem Produkt statt Ihres Startbildschirms.
display
Eines von fullscreen, standalone, minimal-ui oder browser, das beschreibt, wie das PWA-Fenster vom Betriebssystem gezeichnet werden soll. Weitere Informationen zu den verschiedenen Anzeigemodi finden Sie im Kapitel zum App-Design. In den meisten Anwendungsfällen wird standalone implementiert.
id
Ein String, der diese PWA eindeutig im Vergleich zu anderen identifiziert, die möglicherweise am selben Ursprung gehostet werden. Wenn es nicht festgelegt ist, wird start_url als Fallback-Wert verwendet. Wenn Sie start_url ändern, z. B. wenn Sie den Wert eines Abfragestrings ändern, kann der Browser unter Umständen nicht mehr erkennen, dass bereits eine PWA installiert ist.

Symbole

Das Symbol Ihrer PWA ist ihre visuelle Identität in allen Geräte installiert werden, daher ist es wichtig, mindestens eines zu definieren. Da die Eigenschaft icons eine Sammlung von Symbolobjekten ist, können Sie mehrere Symbole in verschiedenen Formaten definieren, um Ihren Nutzern die bestmögliche Symbolerfahrung zu bieten. Jeder Browser wählt ein oder mehrere Symbole basierend auf seinen Anforderungen und dem Betriebssystem aus, auf dem er installiert ist. Die Symbole entsprechen somit eher den erforderlichen Spezifikationen.

Wenn Sie nur eine Symbolgröße auswählen müssen, sollte sie 512 x 512 Pixel groß sein. Es wird jedoch empfohlen, weitere Größen anzugeben, z. B. Bilder in den Größen 192 x 192, 384 x 384 und 1024 x 1024 Pixel.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

Wenn Sie kein Symbol zur Verfügung stellen oder die Symbole nicht die empfohlene Größe haben, erfüllen Sie auf einigen Plattformen die Installationskriterien nicht. Auf anderen Plattformen wird das Symbol automatisch generiert, z. B. aus einem Screenshot der PWA oder durch ein allgemeines Symbol.

Maskierbare Symbole

Einige Betriebssysteme wie Android passen Symbole an verschiedene Größen und Formen an. Unter Android 12 können unterschiedliche Hersteller oder Einstellungen beispielsweise die Form von Symbolen von Kreisen zu Quadraten in Quadrate mit abgerundeten Ecken ändern. Zur Unterstützung solcher adaptiver Symbole können Sie über das Feld purpose ein maskierbares Symbol angeben.

Stellen Sie dazu eine quadratische Bilddatei bereit, bei der das Hauptsymbol in einem sicheren Bereich enthalten ist, einem Kreis in der Mitte des Symbols mit einem Radius von 40 % der Breite des Symbols. (Siehe Abbildung unten.) Geräte, die maskierbare Symbole unterstützen, maskieren Ihr Symbol bei Bedarf.

Der Sicherheitsbereich, der als zentrierter Kreis mit einem Radius von 40 % innerhalb des quadratischen Symbols gekennzeichnet ist

Hier ein Beispiel für ein maskierbares Symbol, das in einer Reihe häufig verwendeter Formen gerendert wird:

Wenn Sie in der folgenden Abbildung das Symbol links als maskierbares Symbol verwenden, wird das Anwenden einer Formmaske auf Geräten am Ende zu schlechten Ergebnissen führen.

Ein Symbol, das sich nicht für ein maskierbares Symbol eignet.

Dieses Bild könnte mit mehr Abstand nutzungsfreundlich gestaltet werden.

Das Symbol mit mehr Abstand eignet sich für Masken.

Maskierbare Symbole sollten mindestens eine Größe von 512 × 512 haben. Nachdem du eine erstellt hast, kannst du sie deiner icons-Sammlung hinzufügen, um die Nutzung für unterstützte Geräte zu verbessern:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

Wenn Ihr maskierbares Symbol nicht gut dargestellt wird, können Sie es verbessern, indem Sie mehr Abstände hinzufügen. Maskable.app ist ein kostenloses Onlinetool zum Testen und Erstellen einer maskierbaren Version Ihres Symbols.

Die nächsten Felder sind Felder, die die Nutzerfreundlichkeit verbessern, auch wenn sie für die Installierbarkeit nicht erforderlich sind.

theme_color
Standardfarbe für die App, die sich manchmal darauf auswirkt, wie das Betriebssystem die Website anzeigt (z. B. Farbe der Fenster- und Titelleiste auf Computern oder die Farbe der Statusleiste auf Mobilgeräten). Diese Farbe kann vom HTML-Element theme-color <meta> überschrieben werden.
background_color
Platzhalterfarbe, die im Hintergrund der App angezeigt wird, bevor das Stylesheet geladen wird. In Safari unter iOS und iPadOS sowie in den meisten Desktop-Browsern wird dieses Feld derzeit ignoriert.
scope
Ändert den Navigationsbereich der PWA, sodass Sie festlegen können, was im Fenster der installierten App angezeigt wird und was nicht. Wenn Sie beispielsweise einen Link zu einer Seite außerhalb dieses Bereichs erstellen, wird sie in einem In-App-Browser und nicht im PWA-Fenster gerendert. Der Geltungsbereich des Service Workers wird dadurch jedoch nicht geändert.

Das nächste Bild zeigt, wie das Feld theme_color für die Titelleiste auf einem Computer verwendet wird, wenn Sie eine PWA installieren.

Dieselbe PWA wurde auf dem Computer mit einer anderen Designfarbe installiert.

Wenn du Farben im Manifest definierst, z. B. in theme_color und background_color, solltest du CSS-benannte Farben wie salmon oder orange, RGB-Farben wie #FF5500 oder Farbfunktionen ohne Transparenz wie rgb() oder hsl() verwenden. Weitere Informationen finden Sie im Kapitel zum App-Design.

Ausprobieren

Ladebildschirme

Auf einigen Geräten wird beim Laden der PWA ein statisches Bild gerendert, um dem Nutzer sofortiges Feedback zu geben.

Android verwendet die Werte theme_color, background_color und icon, um den Ladebildschirm zu generieren.

Wenn Sie eine PWA auf Android installieren, wird auf dem Gerät ein Ladebildschirm mit den Informationen aus Ihrem Manifest erstellt, wie im folgenden Diagramm dargestellt.

Eine PWA auf dem Android-Ladebildschirm, die andere Werte aus dem Manifest übernimmt.

In Safari unter iOS und iPadOS wird hingegen nicht das Web-App-Manifest verwendet, um Startbildschirme zu generieren. Stattdessen wird ein Bild verwendet, das mit einem proprietären <link>-Element verknüpft ist, ähnlich wie Symbole. Weitere Informationen findest du im Kapitel zu Optimierungsfunktionen.

Erweiterte Felder

Die nächsten Felder enthalten zusätzliche Informationen zu Ihrer PWA. ihre Verwendung ist aber optional.

lang
Ein Sprach-Tag, das die primäre Sprache der Werte des Manifests angibt, z. B. en für Englisch, pt-BR für Portugiesisch (Brasilien) oder in für Hindi.
dir
Die Richtung zum Anzeigen richtungsfähiger Manifestfelder (z. B. name, short_name und description). Gültige Werte sind auto, ltr (linksläufig) und rtl (linksläufig).
orientation
Gewünschte Ausrichtung der App nach der Installation Ein Spiel kann dies so einstellen, dass eine Ausrichtung nur im Querformat angefordert wird. Es sind mehrere Werte zulässig, werden aber normalerweise explizit portrait oder landscape angegeben, wenn sie angegeben werden.

Werbefelder

Im vierten Satz von Feldern können Sie Werbeinformationen zu Ihrer PWA angeben, z. B. bei Installationen, Einträgen und Suchergebnissen.

description
Erläuterung der Funktionsweise der PWA
screenshots
Array von Screenshot-Objekten mit src, type und sizes (ähnlich dem icons-Objekt), die die PWA präsentieren sollen Es gibt keine Größenbeschränkungen.
categories
Ein Array von Kategorien, denen die PWA angehören soll, um sie als Hinweise für Einträge zu verwenden, optional aus der Liste der bekannten Kategorien. Diese Werte werden in der Regel in Kleinbuchstaben geschrieben.
iarc_rating_id
Den Zertifizierungscode der International Age Rating Coalition für die PWA, falls vorhanden. Damit lässt sich ermitteln, für welche Altersgruppen Ihre PWA geeignet ist.

Sie können diese Werbefelder schon heute in Aktion sehen. Wenn unter Android Ihre PWA beispielsweise installierbar ist und Sie mindestens Werte für die Felder description und screenshots angeben, wird das Installationsdialogfeld von einer einfachen Schaltfläche „Zum Startbildschirm hinzufügen“ umgewandelt. Infoleiste hin zu einem umfassenderen Installationsdialogfeld, das dem eines App-Shops ähnelt.

Unter Android lässt sich eine übersichtlichere Installations-UI erhalten, wenn Sie Werte für die Werbefelder angeben, wie im nächsten Video gezeigt wird.

Sehen Sie sich diese Werbefelder in Aktion an:

Funktionsfelder

Außerdem gibt es eine Reihe von Feldern, die sich auf die verschiedenen Funktionen beziehen, die Ihre PWA in unterstützten Browsern verwenden kann. Dazu gehören z. B. die Felder shortcuts, share_target und display_overrides, wie im Kapitel zu Funktionen beschrieben. Es gibt auch Felder wie related_apps und prefer_related_apps (weitere Informationen dazu finden Sie im Kapitel zur Erkennung), um Ihre PWA mit installierten Apps zu verbinden, oft über einen App-Shop.

Möglicherweise werden in Zukunft viele neue Felder hinzugefügt, während Browser progressive Web-Apps um zusätzliche Funktionen ergänzen.

Ressourcen