Web-App-Manifest

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

Jede PWA sollte ein einziges Manifest pro Anwendung enthalten. Dieses wird normalerweise im Stammordner gehostet und auf allen HTML-Seiten verlinkt, über die Ihre PWA installiert werden kann. Die offizielle Erweiterung lautet „.webmanifest“, du kannst dein Manifest also so benennen: app.webmanifest.

Web-App-Manifest zu Ihrer PWA hinzufügen

Erstellen Sie zum Erstellen eines Web-App-Manifests zuerst eine Textdatei mit einem JSON-Objekt, das mindestens ein name-Feld mit einem Stringwert enthält:

app.webmanifest:

{
   "name": "My First Application"
}

Allerdings reicht es nicht aus, die Datei zu erstellen. Der Browser muss auch wissen, dass sie existiert.

Mit Manifest verknüpfen

Damit Ihr Web-App-Manifest im Browser erkannt wird, müssen Sie es mit Ihrer PWA verknüpfen. Verwenden Sie dazu ein <link>-HTML-Element und setzen Sie das Attribut rel auf allen HTML-Seiten Ihrer PWA auf manifest. Das funktioniert ähnlich wie die Verknüpfung 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-Datei debuggen

Um sicherzustellen, dass das Manifest korrekt 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 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. Gehen Sie zur Registerkarte Anwendung.
  3. Wählen Sie im linken Steuerfeld die Option „Manifest“ aus.
  4. Prüfen Sie die Felder des Manifests, die vom Browser geparst wurden.

PWA-Nutzung gestalten

Nachdem Ihre PWA mit ihrem Manifest verknüpft ist, müssen Sie die restlichen Felder ausfüllen, um die Nutzererfahrung festzulegen.

Basisfelder

Der erste Satz Felder enthält 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 werden. Sie sind:

name
Vollständiger Name Ihrer PWA. Es erscheint zusammen mit dem Symbol auf dem Startbildschirm, im Launcher, im Dock oder im Menü des Betriebssystems.
short_name
Optional: ein kürzerer Name Ihrer PWA. Er wird verwendet, wenn nicht genügend Platz vorhanden ist, um den vollständigen Wert des Felds „name“ anzuzeigen. Der Text sollte höchstens 12 Zeichen lang sein, damit er nicht abgeschnitten wird.
icons
Array von Symbolobjekten mit den Feldern src, type, sizes und optionalem purpose, die beschreiben, welche Bilder die PWA darstellen sollen.
start_url
Die URL, die geladen werden soll, wenn der Nutzer sie über das installierte Symbol startet. Ein absoluter Pfad wird empfohlen. Wenn die Startseite Ihrer PWA der Stamm Ihrer Website ist, könnten Sie „/“ festlegen, um sie beim Start Ihrer 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, etwa die Details eines Produkts anstelle Ihres Startbildschirms.
display
Eine der folgenden Optionen: fullscreen, standalone, minimal-ui oder browser. Damit wird beschrieben, wie das Betriebssystem das PWA-Fenster darstellen soll. Weitere Informationen zu den verschiedenen Anzeigemodi finden Sie im Kapitel App Design. In den meisten Anwendungsfällen wird standalone implementiert.
id
Ein String, mit dem diese PWA anhand anderer Elemente identifiziert wird, die möglicherweise am selben Ursprung gehostet werden. Ist dies nicht festgelegt, wird start_url als Fallback-Wert verwendet. Wenn Sie „start_url“ später ändern, z. B. wenn Sie den Wert eines Abfragestrings ändern, erkennt der Browser möglicherweise nicht mehr, dass eine PWA bereits installiert ist.

Symbole

Das Symbol Ihrer PWA ist die visuelle Identität auf den Geräten Ihrer Nutzer, wenn diese installiert sind. Daher ist es wichtig, mindestens eines zu definieren. Da es sich bei der Eigenschaft icons um eine Sammlung von Symbolobjekten handelt, können Sie mehrere Symbole in unterschiedlichen Formaten definieren, um Nutzern die bestmögliche Symboldarstellung zu bieten. Jeder Browser wählt ein oder mehrere Symbole entsprechend seinen Anforderungen und dem Betriebssystem aus, auf dem er installiert ist. Die Symbole kommen dann den erforderlichen Spezifikationen näher.

Wenn Sie nur eine Symbolgröße auswählen müssen, sollte diese 512 x 512 Pixel groß sein. Es wird jedoch empfohlen, weitere Größen anzugeben, beispielsweise Bilder mit einer Auflösung von 192 × 192, 384 × 384 und 1.024 × 1.024 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, werden auf einigen Plattformen die Installationskriterien nicht erfüllt. Auf anderen Plattformen wird das Symbol automatisch generiert, z. B. aus einem Screenshot der PWA oder mithilfe eines allgemeinen Symbols.

Maskierbare Symbole

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

Stellen Sie dazu eine quadratische Bilddatei bereit, deren Hauptsymbol sich in einem „sicheren Bereich“ befindet, d. h. 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 nach Bedarf.

Der sichere Bereich, der innerhalb des quadratischen Symbols als Radius von 40 % in der Mitte des Kreises gekennzeichnet ist

Hier ein Beispiel für ein maskierbares Symbol, das in verschiedenen häufig verwendeten Formen gerendert wird:

Wenn Sie in der folgenden Abbildung das Symbol links als maskierbares Symbol verwenden, erhalten Sie auf Geräten mit einer Formmaske schlechte Ergebnisse.

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

Dieses Bild könnte mit mehr Abstand nutzbar gemacht werden.

Das Symbol mit mehr Abstand ist für Masken geeignet.

Maskierbare Symbole sollten mindestens 512 x 512 groß sein. Nachdem Sie ein solches Profil erstellt haben, können Sie es Ihrer Sammlung icons hinzufügen, um die Nutzererfahrung auf unterstützten Geräten 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 richtig angezeigt wird, können Sie es in den meisten Fällen verbessern, indem Sie einen größeren Abstand hinzufügen. 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 einschließen sollten, sind Felder, die die Nutzerfreundlichkeit verbessern, auch wenn sie für die Installation nicht erforderlich sind.

theme_color
Standardfarbe für die App, die sich manchmal auf die Darstellung der Website im Betriebssystem auswirkt (z. B. die Farbe des Fensters und der 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 Safaris unter iOS und iPadOS sowie in den meisten Desktop-Browsern wird dieses Feld derzeit ignoriert.
scope
Hiermit ändern Sie den Navigationsbereich der PWA. Sie können also festlegen, was im Fenster der installierten App angezeigt wird und was nicht. Wenn Sie beispielsweise auf eine Seite außerhalb des Geltungsbereichs verlinken, wird sie in einem In-App-Browser und nicht im PWA-Fenster gerendert. Dies ändert jedoch nicht den Bereich des Service Workers.

Auf der nächsten Abbildung sehen Sie, 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 Sie Farben im Manifest definieren, beispielsweise in theme_color und background_color, sollten Sie CSS-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.

Jetzt testen

Ladebildschirme

Auf einigen Geräten wird ein statisches Bild gerendert, während Ihre PWA geladen wird. So erhält der Nutzer sofort Feedback.

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

Wenn Sie eine PWA unter Android installieren, generiert das Gerät einen Ladebildschirm mit den Informationen aus Ihrem Manifest, wie im folgenden Diagramm dargestellt.

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

Safari unter iOS und iPadOS hingegen verwendet nicht das Web-App-Manifest, um Ladebildschirme zu generieren. Stattdessen wird ein Bild verwendet, das mit einem proprietären <link>-Element verknüpft ist, ähnlich wie bei Symbolen. 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 Hauptsprache der Werte des Manifests angibt, z. B. en für Englisch, pt-BR für brasilianisches Portugiesisch oder in für Hindi.
dir
Die Richtung, in der richtungsfähige Manifestfelder angezeigt werden (z. B. name, short_name und description). Gültige Werte sind auto, ltr (von links nach rechts) und rtl (von rechts nach links).
orientation
Die gewünschte Ausrichtung der App nach der Installation. Bei einem Spiel kann dies so eingestellt werden, dass nur das Querformat angefordert wird. Mehrere Werte werden akzeptiert. Wenn sie enthalten sind, ist sie normalerweise explizit portrait oder landscape.

Felder für Werbeaktionen

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

description
Eine 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
Array von Kategorien, zu denen die PWA gehören soll, um als Hinweise für Einträge verwendet zu werden, optional aus der Liste bekannter Kategorien. Diese Werte werden in der Regel kleingeschrieben.
iarc_rating_id
Der Zertifizierungscode der International Age Rating Coalition für die PWA, falls vorhanden. Sie dient dazu, festzustellen, für welches Alter Ihre PWA geeignet ist.

Sie können diese Felder für Angebote schon heute in Aktion sehen. Wenn Ihre PWA auf Android-Geräten installierbar ist und Sie mindestens für die Felder description und screenshots Werte angeben, wird der Installationsdialog von einer einfachen Infoleiste „Zum Startbildschirm hinzufügen“ in einen umfangreicheren Installationsdialog umgewandelt.

Auf Android-Geräten erhältst du eine bessere Installations-UI, wenn du Werte für die Felder mit Angebotsinformationen angibst, wie du im nächsten Video siehst.

Beispiele für Aktionsfelder:

Funktionsfelder

Außerdem gibt es eine Reihe von Feldern, die sich auf verschiedene Funktionen beziehen, die Ihre PWA in unterstützten Browsern verwenden kann, z. B. die Felder shortcuts, share_target und display_overrides. Weitere Informationen finden Sie im Kapitel zu Funktionen. Außerdem gibt es Felder wie related_apps und prefer_related_apps (weitere Informationen finden Sie im Kapitel zur Erkennung), um Ihre PWA mit installierten Apps zu verknüpfen, häufig aus einem App-Shop.

In Zukunft werden möglicherweise viele neue Felder hinzukommen, während Browser den progressiven Web-Apps weitere Funktionen hinzufügen.

Ressourcen