Web-App-Manifest hinzufügen

Unterstützte Browser

  • 39
  • 79
  • x
  • x

Quelle

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 ist. Eine typische Manifestdatei enthält mindestens Folgendes:

  • Der Name der App
  • Die Symbole, die die App verwenden soll
  • Die URL, die beim Start der App geöffnet werden soll

Manifestdatei erstellen

Die Manifestdatei kann einen beliebigen Namen haben, heißt aber normalerweise manifest.json und wird aus dem Stammverzeichnis (das Verzeichnis der obersten Ebene Ihrer Website) bereitgestellt. Laut der Spezifikation sollte die Erweiterung .webmanifest sein. Möglicherweise möchten Sie JSON-Dateien verwenden, um Ihre Manifeste lesbarer 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 Manifestattribute

short_name und name

Du musst in deinem Manifest entweder short_name oder name angeben. Wenn du beides angibst, wird name verwendet, wenn die App installiert wird, und short_name wird auf dem Startbildschirm, im Launcher des Nutzers oder an anderen Stellen mit begrenztem Speicherplatz verwendet.

icons

Wenn ein Nutzer Ihre PWA installiert, können Sie eine Reihe von Symbolen definieren, die für den Browser auf dem Startbildschirm, im App Launcher, im Aufgabenwechsel, auf dem Ladebildschirm und an anderen Stellen verwendet werden sollen.

Das Attribut icons ist ein Array von Bildobjekten. Jedes Objekt muss das src-Attribut, das sizes-Attribut und den type des Bilds enthalten. Wenn du maskierbare Symbole verwenden möchtest, die unter Android manchmal als adaptive Symbole bezeichnet werden, musst du "purpose": "any maskable" in die Eigenschaft icon einfügen.

Für Chromium müssen Sie mindestens ein Symbol mit 192 × 192 Pixel und ein Symbol mit 512 × 512 Pixeln angeben. Wenn nur diese beiden Symbolgrößen vorhanden sind, skaliert Chrome die Symbole automatisch an das Gerät. Wenn Sie lieber Ihre eigenen Symbole skalieren und für eine Pixelperfektion anpassen möchten, stellen Sie Symbole 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, ist die Abhängigkeit von start_url oder vom Speicherort des Manifests entfernt, sodass diese in Zukunft aktualisiert werden können. Weitere Informationen finden Sie unter PWAs mithilfe der Manifest-ID-Eigenschaft der Web-App eindeutig identifizieren.

start_url

Die start_url ist eine erforderliche Property. Sie teilt dem Browser mit, wo Ihre App beim Start starten soll, und verhindert, dass die App auf der Seite gestartet wird, auf der sich der Nutzer befand, als er die App zu seinem Startbildschirm hinzugefügt hat.

Ihre start_url sollte den Nutzer direkt zu Ihrer App weiterleiten, nicht auf die Produkt-Landingpage. Überlegen Sie, was Nutzende direkt nach dem Öffnen der App tun möchten, und platzieren Sie sie 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-UI beim Starten Ihrer App angezeigt wird. So lassen sich beispielsweise die Adressleiste und die Elemente der Benutzeroberfläche des Browsers ausblenden. Spiele können sogar so gestaltet werden, dass sie im Vollbildmodus gestartet werden. Das Attribut display verwendet einen der folgenden Werte:

Property Behavior
fullscreen Öffnet die Web-App ohne Browser-UI und nimmt den gesamten verfügbaren Anzeigebereich ein.
standalone Öffnet die Web-App, damit sie wie eine eigenständige App aussieht. Sie wird in einem eigenen Fenster ausgeführt, das vom Browser getrennt ist, und blendet Standard-UI-Elemente des Browsers wie die Adressleiste aus.
Beispiel für ein PWA-Fenster mit eigenständigem Display.
Die eigenständige UI.
minimal-ui Dieser Modus ähnelt dem standalone, bietet dem Nutzer jedoch eine minimale Anzahl von UI-Elementen zur Steuerung der Navigation, z. B. die Schaltflächen „Zurück“ und „Aktualisieren“.
Beispiel für ein PWA-Fenster mit minimaler Benutzeroberfläche.
Die minimalistische UI.
browser Eine Standard-Browsererfahrung.

display_override

Um auszuwählen, wie Ihre Web-App angezeigt wird, legen Sie in ihrem Manifest einen display-Modus fest, wie zuvor erläutert. Browser müssen nicht alle Anzeigemodi unterstützen, müssen aber die spezifikationsdefinierte Fallback-Kette ("fullscreen""standalone""minimal-ui""browser") unterstützen. Wenn sie einen bestimmten Modus nicht unterstützen, greifen sie auf den nächsten Anzeigemodus in der Kette zurück. In seltenen Fällen können diese Fallbacks Probleme verursachen. Beispielsweise kann ein Entwickler "minimal-ui" nicht anfordern, ohne in den "browser"-Anzeigemodus zurückzukehren, 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 dem Attribut display_override können Sie eine eigene Fallback-Sequenz festlegen. Dieses Attribut wird im Browser vor dem Attribut display berücksichtigt. Der Wert ist eine Folge von Strings, die in der aufgeführten Reihenfolge berücksichtigt werden. Es wird der erste unterstützte Anzeigemodus angewendet. Werden keine unterstützt, wertet der Browser das Feld display aus. Wenn das Feld display nicht vorhanden ist, wird display_override im Browser ignoriert.

Im Folgenden finden Sie ein Beispiel für die Verwendung von display_override. Die Details von "window-control-overlay" werden auf dieser Seite nicht behandelt.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Beim Laden dieser Anwendung versucht der Browser zuerst, "window-control-overlay" zu verwenden. Sollte dieser nicht verfügbar sein, wird auf "minimal-ui" und dann auf "standalone" aus der display-Property zurückgesetzt. Ist keine dieser Optionen verfügbar, kehrt der Browser zur Standard-Fallback-Kette zurück.

scope

Das scope-Element Ihrer Anwendung ist die Gruppe von URLs, die der Browser als Teil Ihrer Anwendung betrachtet. scope steuert die URL-Struktur, die alle Ein- und Ausstiegspunkte der Anwendung enthält. Der Browser bestimmt anhand dieser URL, wann der Nutzer die Anwendung verlassen hat.

Weitere Hinweise zu scope:

  • Wenn du kein scope in dein Manifest einfügst, ist die standardmäßig implizierte scope die Start-URL. Dateiname, Abfrage und Fragment werden jedoch entfernt.
  • Das Attribut scope kann ein relativer Pfad (../) oder ein beliebiger Pfad auf höherer Ebene (/) sein, mit dem die Abdeckung der Navigationen in Ihrer Web-App erhöht werden kann.
  • start_url muss im Bereich enthalten sein.
  • start_url bezieht sich auf den im scope-Attribut definierten Pfad.
  • Eine start_url, die mit / beginnt, ist immer die Stammebene des Ursprungs.

theme_color

Mit theme_color wird die Farbe der Symbolleiste festgelegt. Sie kann in der Anwendungsvorschau im Task-Wechsler widergespiegelt werden. Der theme_color sollte der Designfarbe meta entsprechen, die im Dokumentkopf angegeben ist.

Beispiel für ein PWA-Fenster mit benutzerdefinierter „theme_color“.
Beispiel für ein PWA-Fenster mit benutzerdefiniertem theme_color.

theme_color in Medienabfragen

Unterstützte Browser

  • 93
  • 93
  • 106
  • 15

Quelle

Sie können theme_color in einer Medienabfrage mithilfe des Attributs media des Designfarbelements meta anpassen. Auf diese Weise können Sie eine Farbe für den hellen Modus und eine andere für den dunklen Modus definieren. Diese Einstellungen lassen sich jedoch nicht in Ihrem Manifest definieren. Weitere Informationen finden Sie unter 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 mit App-Verknüpfungsobjekten, mit denen du schnell auf wichtige Aufgaben in deiner App zugreifen kannst. Jedes Mitglied ist ein Wörterbuch, das mindestens ein name- und ein url-Element enthält.

description

Die Eigenschaft description beschreibt den Zweck Ihrer App.

In Chrome beträgt die maximale Länge der Beschreibung auf allen Plattformen 300 Zeichen. Wenn die Beschreibung länger ist, wird sie vom Browser mit einem Auslassungszeichen gekürzt. Unter Android muss die Beschreibung außerdem maximal sieben Textzeilen enthalten.

screenshots

Das Attribut screenshots ist ein Array von Bildobjekten, die Ihre App in gängigen Nutzungsszenarien darstellen. Jedes Objekt muss das src, das Attribut sizes und das type des Bildes enthalten. Das Attribut form_factor ist optional. Sie können sie entweder auf "wide" für Screenshots, die nur für Breitbildschirme gelten, oder auf "narrow" für nur schmale Screenshots festlegen.

In Chrome muss das Bild die folgenden Kriterien erfüllen:

  • Die Breite und Höhe müssen zwischen 320 und 3.840 Pixel betragen.
  • Die maximale Dimension 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 dem Computer nur Screenshots angezeigt, für die form_factor auf "wide" gesetzt ist.
  • Ab Chrome 109 werden Screenshots, bei denen form_factor auf "wide" gesetzt ist, unter Android ignoriert. Aus Gründen der Abwärtskompatibilität werden trotzdem Screenshots ohne form_factor angezeigt.

In Chrome auf dem Computer werden mindestens ein und höchstens acht Screenshots angezeigt, die diese Kriterien erfüllen. Alle anderen werden ignoriert.

In Chrome unter Android werden mindestens ein und höchstens fünf Screenshots angezeigt, die diese Kriterien erfüllen. Alle anderen werden ignoriert.

Screenshots einer umfangreicheren Installations-UI auf Computern und Mobilgeräten.
Umfassendere Installations-UI auf Computern und Mobilgeräten.

Nachdem du das Manifest erstellt hast, füge allen Seiten deiner progressiven Web-App ein <link>-Tag hinzu. Beispiel:

<link rel="manifest" href="/manifest.json">

Manifest testen

Um zu überprüfen, ob Ihr Manifest korrekt eingerichtet ist, verwenden Sie den Bereich Manifest im Bereich Anwendung der Chrome-Entwicklertools.

Der Anwendungsbereich in den Chrome-Entwicklertools mit ausgewähltem Tab „Manifest“.
Teste dein Manifest in den Entwicklertools.

In diesem Bereich finden Sie eine menschenlesbare Version vieler Eigenschaften Ihres Manifests, mit denen Sie prüfen können, ob alle Images ordnungsgemäß geladen werden.

Ladebildschirme auf Mobilgeräten

Wenn deine App zum ersten Mal auf einem Mobilgerät gestartet wird, kann es einen Moment dauern, bis der Browser gestartet und die ersten Inhalte gerendert werden. Anstelle eines weißen Bildschirms, der den Nutzer denken könnte, dass die App nicht funktioniert, zeigt der Browser bis zum ersten Mal einen Ladebildschirm an.

Chrome erstellt den Ladebildschirm automatisch aus den name, background_color und icons, die in deinem Manifest angegeben sind. Für einen reibungslosen Übergang vom Ladebildschirm zur App muss background_color dieselbe Farbe wie die Ladeseite haben.

Chrome wählt das Symbol aus, das der Geräteauflösung für die Ladebildschirme am ehesten entspricht. In den meisten Fällen ist die Bereitstellung von 192- oder 512 Pixeln Symbolen ausreichend, Sie können jedoch für eine bessere Übereinstimmung zusätzliche Symbole angeben.

Weitere Informationen

Weitere Informationen zu anderen Attributen, die Sie Ihrem Web-App-Manifest hinzufügen können, finden Sie in der Dokumentation zu MDN Web App Manifest.