BeforeInstallPromptEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface BeforeInstallPromptEvent extends Event

Beschreibung

BeforeInstallPromptEvent ist das Interface des Ereignisses beforeinstallprompt. Der Browser löst es am window-Objekt aus, sobald eine Webseite die Bedingungen für die Installation als Progressive Web App (PWA) erfüllt, also bevor er dem Benutzer anbietet, die Seite auf dem Startbildschirm oder als Desktop-App zu installieren. Zu diesen Bedingungen gehören ein gültiges Web-App-Manifest, eine Auslieferung über HTTPS und je nach Browser eine gewisse Interaktion des Benutzers mit der Seite.

Meistens nutzt man das Ereignis, um den automatischen Hinweis des Browsers mit event.preventDefault() zu unterdrücken. Das Ereignisobjekt wird dann gespeichert, und der Installationsdialog erscheint erst später, zum Beispiel wenn der Benutzer auf einen eigenen „App installieren“-Button klickt. Dafür ruft man prompt() auf.

Wichtige Mitglieder:

platforms: ein Array von Zeichenketten mit den Plattformen, für die das Ereignis gilt, z. B. ["web"]. Dieses Mitglied ist inzwischen veraltet.
userChoice: ein Promise, das mit einem Objekt { outcome, platform } erfüllt wird. outcome ist "accepted" oder "dismissed".
prompt(): zeigt den Installationsdialog an und gibt ein Promise mit demselben Ergebnisobjekt zurück.

Nach einer erfolgreichen Installation feuert der Browser außerdem das Ereignis appinstalled am window. Damit kann man z. B. den eigenen Installations-Button ausblenden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, normalerweise `"beforeinstallprompt"`. Ist nur beim Aufruf des Konstruktors `new BeforeInstallPromptEvent(type, options)` von Bedeutung, den man in der Praxis fast nie selbst verwendet.
$options	object	{}	Optionales Objekt mit den Werten aus `EventInit` (`bubbles`, `cancelable`, `composed`) und in älteren Implementierungen zusätzlich `platforms` (`string[]`).

Beispiele

Standard-Hinweis unterdrücken und Ereignis speichern

let deferredPrompt = null;
const installButton = document.querySelector('#install');
installButton.hidden = true;

window.addEventListener('beforeinstallprompt', (event) => {
  // Automatischen Browser-Hinweis verhindern
  event.preventDefault();
  deferredPrompt = event;
  // Eigenen Button anzeigen
  installButton.hidden = false;
  console.log('Installation möglich für:', event.platforms);
});

Installation möglich für: ["web"]

Installationsdialog per Button-Klick auslösen

installButton.addEventListener('click', async () => {
  if (!deferredPrompt) return;

  // Muss innerhalb einer Benutzeraktion aufgerufen werden
  const { outcome } = await deferredPrompt.prompt();
  console.log(`Benutzer hat die Installation ${outcome === 'accepted' ? 'angenommen' : 'abgelehnt'}`);

  // Ein Ereignisobjekt kann nur einmal verwendet werden
  deferredPrompt = null;
  installButton.hidden = true;
});

Benutzer hat die Installation angenommen

Ergebnis über userChoice auswerten und appinstalled beobachten

window.addEventListener('beforeinstallprompt', async (event) => {
  // Ohne preventDefault() zeigt der Browser seinen eigenen Hinweis
  const choice = await event.userChoice;
  console.log('Ergebnis:', choice.outcome, 'Plattform:', choice.platform);
});

window.addEventListener('appinstalled', () => {
  console.log('PWA wurde installiert');
});

Ergebnis: dismissed Plattform: PWA wurde installiert

Feature-Erkennung mit der on-Property

if ('onbeforeinstallprompt' in window) {
  window.onbeforeinstallprompt = (event) => {
    event.preventDefault();
    window.deferredPrompt = event;
  };
} else {
  // Firefox/Safari: Anleitung zur manuellen Installation zeigen
  console.log('beforeinstallprompt wird nicht unterstützt');
}

// Wichtig · Fallstricke

Nicht standardisiert und experimentell: Die API gibt es nur in Chromium-basierten Browsern. Firefox und Safari (auch unter iOS) lösen das Ereignis nicht aus. Unter iOS installiert der Benutzer die App manuell über „Zum Home-Bildschirm“. Deshalb vorher immer die Unterstützung prüfen, z. B. mit 'onbeforeinstallprompt' in window.
prompt() funktioniert nur einmal pro Ereignisobjekt. Ein zweiter Aufruf wirft einen InvalidStateError. Nach einer Ablehnung muss man warten, bis der Browser das Ereignis erneut auslöst.
prompt() braucht eine Benutzeraktion wie einen Klick. Ein Aufruf ohne Aktion schlägt fehl oder wird ignoriert.
Das Ereignis erscheint nur, wenn die Installationskriterien erfüllt sind (Manifest mit name, icons, start_url und display, Auslieferung über HTTPS, oft ein Service Worker). Ist die App bereits installiert, wird es nicht ausgelöst.
Die Eigenschaft platforms ist veraltet, man sollte sich nicht darauf verlassen. Den Rückgabewert von prompt() gibt es erst in neueren Chromium-Versionen. Für ältere Versionen ist userChoice die Alternative.
Den Listener früh registrieren, am besten schon beim Laden des Skripts. Sonst kann das Ereignis ausgelöst werden, bevor jemand darauf hört.

Siehe auch

Event Window Promise BeforeUnloadEvent InstallEvent