Web-App-Manifest

Das Web-App-Manifest ist eine Datei, die Sie erstellen und mit der Sie dem Browser mitteilen, wie Ihre Webinhalte als App im Betriebssystem angezeigt werden sollen. Das Manifest kann grundlegende Informationen wie den Namen, das Symbol und die Farbgebung des Designs der App, erweiterte Einstellungen wie die gewünschte Ausrichtung und App-Verknüpfungen sowie Katalogmetadaten wie Screenshots enthalten.

Jede PWA sollte ein einzelnes Manifest pro Anwendung enthalten, das in der Regel im Stammverzeichnis gehostet und auf allen HTML-Seiten verlinkt ist, von denen aus Ihre PWA installiert werden kann. Die offizielle Erweiterung ist .webmanifest. Sie können Ihr Manifest also beispielsweise app.webmanifest nennen.

PWA ein Web-App-Manifest hinzufügen

Wenn Sie ein Web-App-Manifest erstellen möchten, 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"
}

Das Erstellen der Datei reicht jedoch nicht aus. Der Browser muss auch wissen, dass sie vorhanden ist.

Verknüpfung mit dem Manifest

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 debuggen

Sie können den Inspector in Firefox und die DevTools in jedem Chromium-basierten Browser verwenden, um sicherzustellen, dass das Manifest richtig eingerichtet ist.

Für Chromium-Browser

In den Entwicklertools

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

Für Firefox

  1. Öffnen Sie den Inspector.
  2. Rufen Sie den Tab „Anwendung“ auf.
  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.

PWA-Design

Nachdem Ihre PWA jetzt mit ihrem Manifest verbunden ist, können Sie die restlichen Felder ausfüllen, um die Nutzererfahrung zu definieren.

Einfache Felder

Die ersten Felder enthalten die wichtigsten Informationen zu Ihrer PWA. Sie werden verwendet, um das Symbol und das Fenster der installierten PWA zu erstellen und festzulegen, wie sie gestartet wird. Diese sind:

name
Vollständiger Name Ihrer PWA. Sie 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. Verwenden Sie maximal 12 Zeichen, um das Risiko von Kürzungen zu minimieren.
icons
Array von Symbolobjekten mit den Feldern src, type, sizes und optional purpose, die beschreiben, welche Bilder die PWA repräsentieren sollen.
start_url
Die URL, die die PWA laden soll, wenn der Nutzer sie über das installierte Symbol startet. Wir empfehlen einen absoluten Pfad. Wenn die Startseite Ihrer PWA der Stamm Ihrer Website ist, können Sie „/“ festlegen, damit sie beim Starten der App geöffnet wird. Wenn Sie keine Start-URL angeben, kann der Browser die URL verwenden, über die die PWA installiert wurde. Es kann sich um einen Deeplink handeln, z. B. zu den Details eines Produkts anstelle Ihres Startbildschirms.
display
Eine der Optionen fullscreen, standalone, minimal-ui oder browser, die beschreibt, wie das Betriebssystem das PWA-Fenster zeichnen soll. Weitere Informationen zu den verschiedenen Anzeigemodi finden Sie im Kapitel zum App-Design. standalone wird in den meisten Anwendungsfällen implementiert.
id
Ein String, der diese PWA eindeutig von anderen unterscheidet, die möglicherweise am selben Ursprung gehostet werden. Wenn er nicht festgelegt ist, wird start_url als Fallbackwert verwendet. Wenn Sie start_url später ä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 auf den Geräten Ihrer Nutzer, wenn sie installiert ist. Daher ist es wichtig, mindestens eines zu definieren. Da die Property icons eine Sammlung von Symbolobjekten ist, können Sie mehrere Symbole in verschiedenen Formaten definieren, um Nutzern die bestmögliche Symboldarstellung zu bieten. Jeder Browser wählt je nach Bedarf und Betriebssystem, auf dem er installiert ist, ein oder mehrere Symbole aus, die den erforderlichen Spezifikationen am besten entsprechen.

Wenn Sie nur eine Symbolgröße auswählen müssen, sollte sie 512 × 512 Pixel betragen. Wir empfehlen jedoch, auch Bilder in den Größen 192 × 192, 384 × 384 und 1.024 × 1.024 Pixel bereitzustellen.

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

Wenn Sie kein Symbol angeben oder die Symbole nicht die empfohlenen Größen haben, erfüllen Sie auf einigen Plattformen nicht die Installationskriterien. Auf anderen Plattformen wird das Symbol automatisch generiert, z. B. aus einem Screenshot der PWA oder mit einem generischen Symbol.

Maskierbare Symbole

Einige Betriebssysteme wie Android passen Symbole an verschiedene Größen und Formen an. Unter Android 12 können verschiedene Hersteller oder Einstellungen die Form von Symbolen beispielsweise von Kreisen zu Quadraten oder Quadraten mit abgerundeten Ecken ändern. Um diese Art von adaptiven Symbolen zu unterstützen, können Sie über das Feld purpose ein maskierbares Symbol angeben.

Verwenden Sie dazu eine quadratische Bilddatei, in der sich das Hauptsymbol in einem „sicheren Bereich“ befindet, einem Kreis mit einem Radius von 40 % der Breite des Symbols, der mittig im Symbol platziert ist. (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 im folgenden Bild das Symbol auf der linken Seite als maskierbares Symbol verwenden, erhalten Sie auf Geräten schlechte Ergebnisse, wenn eine Formmaske angewendet wird.

Ein Symbol, das nicht für ein maskierbares Symbol geeignet ist.

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

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

Maskierbare Symbole sollten mindestens 512 × 512 Pixel groß sein. 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 in den meisten Fällen nicht gut angezeigt wird, können Sie es durch mehr Abstand verbessern. Maskable.app ist ein kostenloses Onlinetool, mit dem Sie eine maskierbare Version Ihres Symbols testen und erstellen können.

Die nächsten Felder, die Sie einfügen sollten, verbessern die Nutzerfreundlichkeit, sind aber für die Installation nicht erforderlich.

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 Anwendung angezeigt wird, bevor das Stylesheet geladen wird. In Safari auf iOS und iPadOS sowie in den meisten Desktop-Browsern wird dieses Feld derzeit ignoriert.
scope
Ändert den Navigationsbereich der PWA. So können Sie festlegen, was im Fenster der installierten App angezeigt wird und was nicht. Wenn Sie beispielsweise einen Link zu einer Seite außerhalb des Gültigkeitsbereichs setzen, wird diese Seite in einem In-App-Browser statt in Ihrem PWA-Fenster gerendert. Der Umfang Ihres Service Workers ändert sich dadurch jedoch nicht.

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

Dieselbe PWA, die auf einem Computer mit einer anderen Farbgebung installiert ist.

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 während des Ladens Ihrer PWA ein statisches Bild gerendert, um dem Nutzer sofort 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, generiert das Gerät einen Splashscreen mit den Informationen aus Ihrem Manifest, wie im folgenden Diagramm dargestellt.

Eine PWA auf dem Android-Startbildschirm, die unterschiedliche Werte aus dem Manifest verwendet.

Safari auf iOS und iPadOS verwendet das Web-App-Manifest hingegen nicht, um Splashscreens zu generieren. Stattdessen wird ein Bild verwendet, das über ein proprietäres <link>-Element verknüpft ist, ähnlich wie bei Symbolen. Weitere Informationen finden Sie im Kapitel zur Optimierung.

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, in der richtungsfähige Manifestfelder wie name, short_name und description angezeigt werden. Gültige Werte sind auto, ltr (linksläufig) und rtl (linksläufig).
orientation
Die gewünschte Ausrichtung der App nach der Installation. Ein Spiel kann diese Einstellung so festlegen, dass nur das Querformat angefordert wird. Mehrere Werte sind zulässig. Wenn sie angegeben werden, ist es in der Regel portrait oder landscape.

Angebotsfelder

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 Screenshotobjekten mit src, type und sizes (ähnlich dem icons-Objekt), das die PWA präsentieren soll. Es gibt keine Größenbeschränkungen.
categories
Array von Kategorien, zu denen die PWA gehören sollte, um als Hinweise für Einträge verwendet zu werden, optional aus der Liste der bekannten Kategorien. Diese Werte werden in der Regel in Kleinbuchstaben geschrieben.
iarc_rating_id
Der Zertifizierungscode der International Age Rating Coalition für die PWA, falls vorhanden. Damit soll festgelegt werden, für welche Altersgruppen Ihre PWA geeignet ist.

Sie können diese Angebotsfelder bereits jetzt verwenden. Wenn Ihre PWA beispielsweise auf Android-Geräten installiert werden kann und Sie Werte für mindestens die Felder description und screenshots angeben, wird das Installationsdialogfeld von einer einfachen Infoleiste „Zum Startbildschirm hinzufügen“ in ein umfangreicheres Installationsdialogfeld umgewandelt, das dem eines App-Shops ähnelt.

Unter Android können Sie die Installationsoberfläche ansprechender gestalten, wenn Sie Werte für die Werbefelder angeben. Das sehen Sie im nächsten Video.

Hier sehen Sie diese Angebotsfelder in Aktion:

Funktionsfelder

Außerdem gibt es eine Reihe von Feldern zu verschiedenen Funktionen, die Ihre PWA in unterstützten Browsern verwenden kann, z. B. die Felder shortcuts, share_target und display_override, die im Kapitel zu Funktionen behandelt werden. Es gibt auch Felder wie related_apps und prefer_related_apps (weitere Informationen finden Sie im Kapitel zur Erkennung), mit denen Sie Ihre PWA mit installierten Apps verbinden können, oft aus einem App-Shop.

In Zukunft werden möglicherweise weitere Felder hinzugefügt, wenn Browser progressive Web-Apps weitere Funktionen hinzufügen.

Ressourcen