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
- Wählen Sie im linken Bereich unter Anwendung die Option Manifest aus.
- Prüfen Sie die Felder des Manifests, die vom Browser geparst wurden.
Für Firefox
- Öffnen Sie den Inspector.
- Gehen Sie zur Registerkarte Anwendung.
- Wählen Sie im linken Steuerfeld die Option „Manifest“ aus.
- 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 optionalempurpose
, 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
oderbrowser
. 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 wirdstandalone
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.
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.
Dieses Bild könnte mit mehr Abstand nutzbar gemacht werden.
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.
Empfohlene Felder
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.
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.
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 oderin
für Hindi. dir
- Die Richtung, in der richtungsfähige Manifestfelder angezeigt werden (z. B.
name
,short_name
unddescription
). Gültige Werte sindauto
,ltr
(von links nach rechts) undrtl
(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
oderlandscape
.
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
undsizes
(ähnlich demicons
-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.