Ein Web-App-Manifest ist eine JSON-Datei, die dem Browser mitteilt, wie sich Ihre Progressive Web-App (PWA) verhalten soll, wenn sie auf dem Computer oder Mobilgerät des Nutzers installiert wird. Eine typische Manifestdatei enthält mindestens Folgendes:
- Name der App
- Die Symbole, die in der App verwendet werden sollen
- Die URL, die beim Starten der App geöffnet werden soll
Manifestdatei erstellen
Die Manifestdatei kann einen beliebigen Namen haben, wird aber in der Regel manifest.json
genannt und vom Stammverzeichnis (dem Top-Level-Verzeichnis Ihrer Website) aus bereitgestellt. In der Spezifikation wird die Erweiterung .webmanifest
empfohlen. Sie können aber auch JSON-Dateien verwenden, um Ihre Manifeste besser lesbar zu machen.
Ein typisches Manifest sieht so aus:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
Wichtige Manifest-Eigenschaften
short_name
und name
Sie müssen in Ihrem Manifest mindestens short_name
oder name
angeben. Wenn Sie beides angeben, wird name
bei der Installation der App und short_name
auf dem Startbildschirm, im Launcher oder an anderen Stellen verwendet, an denen wenig Platz ist.
icons
Wenn ein Nutzer Ihre PWA installiert, können Sie eine Reihe von Symbolen für den Browser definieren, die auf dem Startbildschirm, im App Launcher, im Task-Switcher, auf dem Ladebildschirm und an anderen Stellen verwendet werden.
Die Property icons
ist ein Array von Bildobjekten. Jedes Objekt muss die src
, eine sizes
-Property und die type
des Bilds enthalten. Wenn Sie maskierbare Symbole verwenden möchten, die unter Android manchmal als adaptive Symbole bezeichnet werden, fügen Sie der Property icon
das Attribut "purpose": "any maskable"
hinzu.
Für Chromium müssen Sie mindestens ein Symbol mit 192 x 192 Pixeln und ein Symbol mit 512 x 512 Pixeln angeben. Wenn nur diese beiden Symbolgrößen angegeben sind, skaliert Chrome die Symbole automatisch an das Gerät an. Wenn Sie Ihre eigenen Symbole lieber skalieren und pixelgenau anpassen möchten, stellen Sie sie in Schritten von 48 dp bereit.
id
Mit dem Attribut id
können Sie die für Ihre Anwendung verwendete ID explizit definieren. Wenn Sie dem Manifest das Attribut id
hinzufügen, wird die Abhängigkeit von start_url
oder dem Speicherort des Manifests aufgehoben und es ist möglich, sie in Zukunft zu aktualisieren. Weitere Informationen finden Sie unter PWAs mithilfe der Manifest-ID der Web-App eindeutig identifizieren.
start_url
start_url
ist ein erforderliches Attribut. Sie teilt dem Browser mit, wo Ihre Anwendung beim Start starten soll, und verhindert, dass die Anwendung auf der Seite startet, auf der sich der Nutzer befand, als er Ihre Anwendung dem Startbildschirm hinzugefügt hat.
Ihre start_url
sollte Nutzer direkt zu Ihrer App und nicht zu einer Produkt-Landingpage weiterleiten. Überlegen Sie, was Nutzer direkt nach dem Öffnen Ihrer App tun möchten, und platzieren Sie die entsprechenden Elemente dort.
background_color
Das Attribut background_color
wird auf dem Ladebildschirm verwendet, wenn die App zum ersten Mal auf einem Mobilgerät gestartet wird.
display
Sie können anpassen, welche Browser-Benutzeroberfläche beim Starten Ihrer App angezeigt wird. Sie können beispielsweise die Adressleiste und die Elemente der Browseroberfläche ausblenden. Spiele können sogar im Vollbildmodus gestartet werden. Das Attribut display
kann einen der folgenden Werte haben:
Attribut | Verhalten |
---|---|
fullscreen |
Die Webanwendung wird ohne Browser-Benutzeroberfläche geöffnet und nimmt den gesamten verfügbaren Anzeigebereich ein. |
standalone |
Öffnet die Web-App so, dass sie wie eine eigenständige App aussieht. Sie wird in einem eigenen Fenster ausgeführt, das vom Browser getrennt ist, und blendet standardmäßige Browser-UI-Elemente wie die Adressleiste aus. |
minimal-ui |
Dieser Modus ähnelt standalone , bietet dem Nutzer jedoch nur eine minimale Anzahl von UI-Elementen zur Steuerung der Navigation, z. B. die Schaltflächen „Zurück“ und „Aktualisieren“.
|
browser |
Ein Standardbrowser. |
display_override
Wenn Sie auswählen möchten, wie Ihre Webanwendung angezeigt wird, legen Sie im Manifest den Modus display
fest, wie zuvor erläutert. Browser müssen nicht alle Displaymodi unterstützen, aber müssen die in der Spezifikation definierte Fallback-Kette ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
) unterstützen. Wenn ein bestimmter Modus nicht unterstützt wird, wird auf den nächsten Displaymodus in der Kette zurückgegriffen. In seltenen Fällen können diese Fallbacks zu Problemen führen. Ein Entwickler kann beispielsweise "minimal-ui"
nicht anfordern, ohne zum Anzeigemodus "browser"
zurückgezwungen zu werden, wenn "minimal-ui"
nicht unterstützt wird. Aufgrund des aktuellen Verhaltens ist es auch nicht möglich, neue Darstellungsmodi auf abwärtskompatible Weise einzuführen, da sie keinen Platz in der Fallback-Kette haben.
Mit der Property display_override
können Sie eine eigene Fallback-Sequenz festlegen, die vom Browser vor der Property display
berücksichtigt wird. Sein Wert ist eine Folge von Strings, die in der aufgeführten Reihenfolge berücksichtigt werden. Der erste unterstützte Anzeigemodus wird angewendet. Wenn keine unterstützt werden, greift der Browser auf die Auswertung des Felds display
zurück. Wenn kein display
-Feld vorhanden ist, ignoriert der Browser display_override
.
Im Folgenden finden Sie ein Beispiel für die Verwendung von display_override
. Die Details zu "window-control-overlay"
fallen nicht in den Zuständigkeitsbereich dieser Seite.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Beim Laden dieser App versucht der Browser zuerst, "window-control-overlay"
zu verwenden. Ist das nicht verfügbar, wird auf "minimal-ui"
und dann auf "standalone"
aus dem Attribut display
zurückgegriffen. Wenn keine dieser Optionen verfügbar ist, kehrt der Browser zur Standard-Fallback-Kette zurück.
scope
Das scope
Ihrer Anwendung ist die Gruppe von URLs, die der Browser als Teil Ihrer Anwendung betrachtet. scope
steuert die URL-Struktur, die alle Ein- und Ausgangspunkte zur Anwendung enthält. Der Browser bestimmt anhand dieser URL, wann der Nutzer die Anwendung verlassen hat.
Weitere Hinweise zu scope
:
- Wenn Sie kein
scope
in Ihr Manifest aufnehmen, ist die implizierte Standard-scope
die Start-URL. Dateiname, Abfrage und Fragment wurden jedoch entfernt. - Das Attribut
scope
kann ein relativer Pfad (../
) oder ein Pfad einer höheren Ebene (/
) sein, mit dem die Abdeckung der Navigation in Ihrer Webanwendung erhöht werden kann. - Die
start_url
muss im Geltungsbereich liegen. start_url
ist relativ zum Pfad, der im Attributscope
definiert ist.- Ein
start_url
, der mit/
beginnt, ist immer der Stamm des Ursprungs.
theme_color
Mit dem theme_color
wird die Farbe der Symbolleiste festgelegt. Sie kann in der Vorschau der App in Task-Switchern berücksichtigt werden. Die theme_color
sollte mit der im Dokumentkopf angegebenen meta
-Designfarbe übereinstimmen.
theme_color
in Medienabfragen
Sie können theme_color
in einer Medienabfrage mit dem media
-Attribut des meta
-Farbelements für das Design anpassen. Auf diese Weise können Sie beispielsweise eine Farbe für den hellen Modus und eine andere für den dunklen Modus definieren. Sie können diese Einstellungen jedoch nicht in Ihrem Manifest definieren. Weitere Informationen finden Sie im GitHub-Problem w3c/manifest#975.
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
Das Attribut shortcuts
ist ein Array von App-Verknüpfungsobjekten, die schnellen Zugriff auf wichtige Aufgaben in Ihrer App bieten. Jedes Mitglied ist ein Wörterbuch, das mindestens ein name
und ein url
enthält.
description
Die Property description
beschreibt den Zweck Ihrer App.
In Chrome beträgt die maximale Länge einer Beschreibung auf allen Plattformen 300 Zeichen. Ist die Beschreibung länger, wird sie vom Browser mit einem Auslassungszeichen abgeschnitten. Auf Android-Geräten darf die Beschreibung außerdem maximal sieben Textzeilen umfassen.
screenshots
Das Attribut screenshots
ist ein Array von Bildobjekten, die Ihre Anwendung in gängigen Nutzungsszenarien darstellen. Jedes Objekt muss die src
, eine sizes
-Property und die type
des Bilds enthalten. Das Attribut form_factor
ist optional.
Sie können entweder "wide"
für Screenshots festlegen, die nur für breite Bildschirme gelten, oder "narrow"
für nur schmale Screenshots.
In Chrome muss das Bild die folgenden Kriterien erfüllen:
- Breite und Höhe müssen mindestens 320 Pixel und höchstens 3.840 Pixel betragen.
- Die Maximalgröße darf nicht mehr als das 2,3-fache der Länge der Mindestgröße betragen.
- Alle Screenshots, die dem entsprechenden Formfaktor entsprechen, müssen dasselbe Seitenverhältnis haben.
- Ab Chrome 109 werden auf dem Computer nur Screenshots angezeigt, bei denen
form_factor
auf"wide"
festgelegt ist.
- Ab Chrome 109 werden auf dem Computer nur Screenshots angezeigt, bei denen
- Ab Chrome 109 werden Screenshots, bei denen
form_factor
auf"wide"
festgelegt ist, unter Android ignoriert. Screenshots ohneform_factor
werden aus Gründen der Abwärtskompatibilität weiterhin angezeigt.
In Chrome auf dem Computer werden mindestens ein und maximal acht Screenshots angezeigt, die diese Kriterien erfüllen. Der Rest wird ignoriert.
Chrome unter Android zeigt mindestens einen und höchstens fünf Screenshots an, die diese Kriterien erfüllen. Alle anderen werden ignoriert.
Ihren Seiten das Manifest der Webanwendung hinzufügen
Nachdem Sie das Manifest erstellt haben, fügen Sie allen Seiten Ihrer progressiven Web-App ein <link>
-Tag hinzu. Beispiel:
<link rel="manifest" href="/manifest.json">
Manifest testen
Prüfen Sie im Chrome-Entwicklertool im Bereich Anwendung im Bereich Manifest, ob Ihr Manifest richtig eingerichtet ist.
In diesem Bereich finden Sie eine für Menschen lesbare Version vieler Manifesteigenschaften. Außerdem können Sie prüfen, ob alle Bilder richtig geladen werden.
Splashscreens auf Mobilgeräten
Wenn Ihre App auf einem Mobilgerät zum ersten Mal gestartet wird, kann es einen Moment dauern, bis der Browser gestartet und die ersten Inhalte gerendert werden. Anstelle eines weißen Bildschirms, der Nutzer vermuten lässt, dass die App nicht funktioniert, wird im Browser bis zum ersten Anstrich ein Ladebildschirm angezeigt.
Chrome erstellt den Startbildschirm automatisch aus den in Ihrem Manifest angegebenen name
-, background_color
- und icons
-Werten. Für einen reibungslosen Übergang vom Begrüßungsbildschirm zur App muss für background_color
dieselbe Farbe wie für die Ladeseite verwendet werden.
Chrome wählt für die Startbildschirme das Symbol aus, das der Geräteauflösung am besten entspricht. In den meisten Fällen reichen Symbole mit 192 × 192 Pixeln und 512 × 512 Pixeln aus. Sie können aber auch zusätzliche Symbole angeben, um eine bessere Übereinstimmung zu erzielen.
Weitere Informationen
Weitere Informationen zu anderen Properties, die Sie dem Manifest Ihrer Webanwendung hinzufügen können, finden Sie in der MDN-Manifestdokumentation für Webanwendungen.