Eigene In-App-Installationskampagnen bereitstellen

In vielen Browsern ist es möglich, die Installation einer progressiven Web-App (PWA) direkt in der Benutzeroberfläche der PWA zu aktivieren und zu fördern. Die Installation (früher „Zum Startbildschirm hinzufügen“) erleichtert Nutzern die Installation Ihrer PWA auf ihrem Mobilgerät oder Computer. Wenn Sie eine PWA installieren, wird sie dem Launcher des Nutzers hinzugefügt, sodass sie wie jede andere installierte App ausgeführt werden kann.

Zusätzlich zur Installation im Browser kannst du direkt in deiner App einen eigenen benutzerdefinierten Installationsablauf bereitstellen.

Schaltfläche „App installieren“ in der Spotify-PWA
Schaltfläche „App installieren“ in der Spotify-PWA

Wenn Sie für die Installation werben möchten, sollten Sie sich überlegen, wie Nutzer Ihre PWA normalerweise verwenden. Wenn beispielsweise eine Gruppe von Nutzern Ihre PWA mehrmals in der Woche verwendet, können diese Nutzer von dem zusätzlichen Komfort profitieren, die App über den Startbildschirm eines Smartphones oder über das Startmenü eines Desktop-Betriebssystems zu starten. Einige Produktivitäts- und Unterhaltungsanwendungen profitieren auch von der zusätzlichen Bildschirmfläche, die erstellt wird, indem die Symbolleisten des Browsers im installierten standalone- oder minimal-ui-Modus aus dem Fenster entfernt werden.

Voraussetzungen

Prüfen Sie zuerst, ob Ihre PWA die Anforderungen an die Installierbarkeit erfüllt. Dazu gehört in der Regel ein Manifest für Web-Apps.

Installation fördern

So geben Sie an, dass Ihre progressive Web-App installierbar ist, und bieten einen benutzerdefinierten In-App-Installationsvorgang:

  1. Warten Sie auf das Ereignis beforeinstallprompt.
  2. Speichern Sie das beforeinstallprompt-Ereignis, damit es später zum Auslösen der Installation verwendet werden kann.
  3. Weisen Sie Nutzer darauf hin, dass Ihre PWA installierbar ist, und geben Sie eine Schaltfläche oder ein anderes Element an, um den In-App-Installationsvorgang zu starten.

Auf das Ereignis beforeinstallprompt warten

Wenn deine progressive Web-App die erforderlichen Installationskriterien erfüllt, löst der Browser ein beforeinstallprompt-Ereignis aus. Speichern Sie einen Verweis auf das Ereignis und aktualisieren Sie die Benutzeroberfläche, um anzugeben, dass der Nutzer Ihre PWA installieren kann.

// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the mini-infobar from appearing on mobile
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can install the PWA
  showInstallPromotion();
  // Optionally, send analytics event that PWA install promo was shown.
  console.log(`'beforeinstallprompt' event was fired.`);
});

Ablauf der In-App-Installation

Wenn Sie eine In-App-Installation ermöglichen möchten, müssen Sie eine Schaltfläche oder ein anderes Oberflächenelement bereitstellen, über das der Nutzer Ihre App installieren kann. Wenn auf das Element geklickt wird, rufen Sie prompt() für das gespeicherte beforeinstallprompt-Ereignis auf, das in der Variablen deferredPrompt gespeichert ist. Der Nutzer sieht ein modales Installationsdialogfeld, in dem er bestätigen muss, dass er die PWA installieren möchte.

buttonInstall.addEventListener('click', async () => {
  // Hide the app provided install promotion
  hideInstallPromotion();
  // Show the install prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  // Optionally, send analytics event with outcome of user choice
  console.log(`User response to the install prompt: ${outcome}`);
  // We've used the prompt, and can't use it again, throw it away
  deferredPrompt = null;
});

Das Attribut userChoice ist ein Versprechen, das entsprechend der Auswahl des Nutzers aufgelöst wird. Sie können prompt() bei dem verzögerten Ereignis nur einmal aufrufen. Wenn der Nutzer sie schließt, müssen Sie warten, bis das beforeinstallprompt-Ereignis wieder ausgelöst wird, in der Regel direkt, nachdem das Attribut userChoice aufgelöst wurde.

Erkennen, wann die PWA erfolgreich installiert wurde

Mit dem Attribut userChoice können Sie feststellen, ob der Nutzer die Anwendung über die Benutzeroberfläche installiert hat. Wenn der Nutzer deine PWA über die Adressleiste oder eine andere Browserkomponente installiert, hilft userChoice nicht. Warten Sie stattdessen auf das Ereignis appinstalled. Sie wird immer dann ausgelöst, wenn Ihre PWA installiert ist, unabhängig davon, über welchen Mechanismus sie installiert wird.

window.addEventListener('appinstalled', () => {
  // Hide the app-provided install promotion
  hideInstallPromotion();
  // Clear the deferredPrompt so it can be garbage collected
  deferredPrompt = null;
  // Optionally, send analytics event to indicate successful install
  console.log('PWA was installed');
});

Ermitteln, wie die PWA gestartet wurde

Die CSS-Medienabfrage display-mode gibt an, wie die PWA gestartet wurde, entweder in einem Browsertab oder als installierte PWA. Dadurch können unterschiedliche Stile angewendet werden, je nachdem, wie die App eingeführt wurde. Beispielsweise sollten Sie die Installationsschaltfläche immer ausblenden und eine Schaltfläche „Zurück“ bereitstellen, wenn sie als installierte PWA gestartet wird.

Nachverfolgen, wie die PWA gestartet wurde

Wenn Sie wissen möchten, wie Nutzer Ihre PWA starten, testen Sie mit matchMedia() die Medienabfrage display-mode. Safari unter iOS unterstützt dies noch nicht. Deshalb müssen Sie navigator.standalone prüfen. Es wird ein boolescher Wert zurückgegeben, der angibt, ob der Browser im eigenständigen Modus ausgeführt wird.

function getPWADisplayMode() {
  const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
  if (document.referrer.startsWith('android-app://')) {
    return 'twa';
  } else if (navigator.standalone || isStandalone) {
    return 'standalone';
  }
  return 'browser';
}

Änderungen des Anzeigemodus erfassen

Wenn Sie erfassen möchten, ob der Nutzer zwischen standalone und browser tab wechselt, warten Sie auf Änderungen an der display-mode-Medienabfrage.

window.matchMedia('(display-mode: standalone)').addEventListener('change', (evt) => {
  let displayMode = 'browser';
  if (evt.matches) {
    displayMode = 'standalone';
  }
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', displayMode);
});

UI basierend auf dem aktuellen Anzeigemodus aktualisieren

Wenn Sie für eine PWA eine andere Hintergrundfarbe festlegen möchten, wenn sie als installierte PWA gestartet wird, können Sie bedingtes CSS verwenden:

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

Symbol und Namen der App aktualisieren

Was ist, wenn Sie den Namen Ihrer App aktualisieren oder neue Symbole bereitstellen müssen? Unter Wie Chrome mit Aktualisierungen des Web-App-Manifests umgeht erfahren Sie, wann und wie diese Änderungen in Chrome angezeigt werden.