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, heißt aber in der Regel manifest.json und wird aus dem Stammverzeichnis (der obersten Ebene Ihrer Website) 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

Du musst in deinem Manifest mindestens entweder 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 Aufgabenauswahl, auf dem Ladebildschirm und an anderen Stellen verwendet werden sollen.

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 der Property id können Sie die Kennung für Ihre Anwendung 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 gibt dem Browser an, wo Ihre App beim Starten beginnen soll, und verhindert, dass die App auf der Seite gestartet wird, auf der sich der Nutzer befand, als er Ihre App auf dem Startbildschirm hinzugefügt hat.

start_url sollte den Nutzer direkt zu Ihrer App weiterleiten, nicht zu einer Produkt-Landingpage. Ü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 Startbildschirm 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. So können Sie 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	Öffnet die Web-App ohne Browser-UI und nimmt den gesamten verfügbaren Anzeigebereich ein.
standalone	Die Webanwendung wird so geöffnet, dass sie wie eine eigenständige App aussieht. Sie wird in einem eigenen Fenster ausgeführt, getrennt vom Browser, und standardmäßige Browser-UI-Elemente wie die Adressleiste werden ausgeblendet.
minimal-ui	Dieser Modus ähnelt standalone, bietet Nutzern aber eine minimale Anzahl von UI-Elementen zur Navigation, z. B. die Schaltflächen „Zurück“ und „Aktualisieren“.
browser	Standardbrowser

display_override

Wenn Sie festlegen möchten, wie Ihre Webanwendung angezeigt wird, legen Sie im Manifest einen display-Modus fest, wie bereits 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 Probleme verursachen. Beispielsweise kann ein Entwickler "minimal-ui" nicht anfordern, ohne in den Anzeigemodus "browser" zurückgeführt zu werden, wenn "minimal-ui" nicht unterstützt wird. Das aktuelle Verhalten macht es auch nicht möglich, neue Anzeigemodi 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. Der Wert ist eine Sequenz von Strings, die in der angegebenen 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.

Das folgende Beispiel zeigt, wie display_override verwendet wird. Die Details von "window-control-overlay" werden auf dieser Seite nicht behandelt.

{
  "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

Die scope Ihrer App ist die Gruppe von URLs, die der Browser als Teil Ihrer App betrachtet. scope steuert die URL-Struktur, die alle Einstiegs- und Ausstiegspunkte zur App enthält. Der Browser verwendet sie, um zu ermitteln, wann der Nutzer die App verlassen hat.

Weitere Hinweise zu scope:

• Wenn Sie in Ihrem Manifest keine scope angeben, ist die implizite Standardscope die Start-URL, aus der der Dateiname, die Abfrage und das Fragment entfernt wurden.
• Das Attribut scope kann ein relativer Pfad (../) oder ein Pfad auf höherer Ebene (/) sein, der eine größere Abdeckung der Navigation in Ihrer Webanwendung ermöglichen würde.
• Die start_url muss im Geltungsbereich liegen.
• start_url ist relativ zum Pfad, der im Attribut scope definiert ist.
• Ein start_url, das mit / beginnt, ist immer die Wurzel 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. So 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

Die screenshots-Eigenschaft ist ein Array von Bildobjekten, die Ihre App 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 Mindestdimension betragen.
• Alle Screenshots, die mit dem entsprechenden Formfaktor übereinstimmen, müssen dasselbe Seitenverhältnis haben.
  • Ab Chrome 109 werden auf Computern nur Screenshots angezeigt, bei denen form_factor auf "wide" gesetzt 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. Der Rest wird ignoriert.

Ihren Seiten das Manifest der Webanwendung hinzufügen

Fügen Sie nach dem Erstellen des Manifests allen Seiten Ihrer Progressiven Webanwendung 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.

Dieser Bereich enthält eine menschenlesbare Version vieler Manifest-Attribute und bietet Ihnen die Möglichkeit, zu prüfen, ob alle Bilder ordnungsgemäß geladen werden.

Splashscreens auf Mobilgeräten

Wenn deine App zum ersten Mal auf einem Mobilgerät gestartet wird, kann es einen Moment dauern, bis der Browser startet und der erste Inhalt gerendert wird. Anstatt einen weißen Bildschirm anzuzeigen, der den Nutzer möglicherweise glauben lässt, dass die App nicht funktioniert, zeigt der Browser bis zur ersten Paint-Operation einen Splashscreen an.

Chrome erstellt den Startbildschirm automatisch aus den in Ihrem Manifest angegebenen name-, background_color- und icons-Werten. Für einen reibungslosen Übergang vom Splashscreen zur App sollten Sie background_color dieselbe Farbe wie die Ladeseite verwenden.

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.