Web-App-Manifest hinzufügen

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

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 Attribut scope 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 Screenshots, bei denen form_factor auf "wide" festgelegt ist, unter Android ignoriert. Screenshots ohne form_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.