Window: beforeinstallprompt — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("beforeinstallprompt", handler)

Beschreibung

Das Ereignis beforeinstallprompt feuert, sobald eine Seite die Installationskriterien des Browsers erfüllt – typischerweise ein gültiges Web-App-Manifest (mit name, icons, start_url, display), Auslieferung über HTTPS und je nach Browser weitere Voraussetzungen. Das übergebene Ereignisobjekt ist ein BeforeInstallPromptEvent.

Der Hauptnutzen: Ruft man event.preventDefault() auf, unterdrückt man die automatische Installationsleiste bzw. das Mini-Infobar des Browsers. Speichert man das Ereignis zwischen, kann man später – etwa nach Klick auf einen eigenen „App installieren“-Button – event.prompt() aufrufen und den Installationsdialog zu einem passenden Zeitpunkt anzeigen. Über das Promise event.userChoice erfährt man, ob die Person zugestimmt ("accepted") oder abgelehnt ("dismissed") hat.

Registrieren lässt sich der Handler per window.addEventListener("beforeinstallprompt", handler) oder über die Eigenschaft window.onbeforeinstallprompt = handler. Nach erfolgreicher Installation feuert am window zusätzlich das Ereignis appinstalled.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"beforeinstallprompt"`.
$handler Pflicht	(event: BeforeInstallPromptEvent) => void		Callback, der das `BeforeInstallPromptEvent` erhält. Wichtige Mitglieder: `preventDefault()`, `prompt()` (gibt ein Promise zurück), `userChoice` (Promise mit `{ outcome, platform }`) und `platforms` (Array von Plattform-Strings).
$options	boolean\|AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `capture` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein BeforeInstallPromptEvent.

Beispiele

Eigenen Installations-Button anbieten

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

window.addEventListener('beforeinstallprompt', (event) => {
  // Standard-Infobar des Browsers unterdrücken
  event.preventDefault();
  deferredPrompt = event;
  installBtn.hidden = false;
});

installBtn.addEventListener('click', async () => {
  if (!deferredPrompt) return;
  installBtn.hidden = true;
  await deferredPrompt.prompt();
  const { outcome } = await deferredPrompt.userChoice;
  console.log(`Installationsdialog: ${outcome}`);
  // Ein Event kann nur einmal prompt() aufrufen
  deferredPrompt = null;
});

Installationsdialog: accepted

Über die on-Property und appinstalled

window.onbeforeinstallprompt = (event) => {
  console.log('Installierbar auf:', event.platforms);
};

window.addEventListener('appinstalled', () => {
  console.log('PWA wurde installiert');
  // Handler entfernen, da nicht mehr nötig
  window.onbeforeinstallprompt = null;
});

Installierbar auf: ["web"] PWA wurde installiert

Listener wieder entfernen und Feature-Erkennung

const onBeforeInstall = (event) => {
  event.preventDefault();
  console.log('Installation möglich – Hinweis später zeigen');
};

if ('onbeforeinstallprompt' in window) {
  window.addEventListener('beforeinstallprompt', onBeforeInstall);
} else {
  console.log('Kein beforeinstallprompt – z. B. Safari: Anleitung „Zum Home-Bildschirm“ zeigen');
}

// Z. B. wenn der Nutzer Installationshinweise dauerhaft abgelehnt hat
const optOut = () => window.removeEventListener('beforeinstallprompt', onBeforeInstall);
optOut();

Installation möglich – Hinweis später zeigen

// Wichtig · Fallstricke

Nicht standardisiert und nur in Chromium-Browsern: Firefox (Desktop) und Safari lösen das Ereignis nicht aus. Nutze immer Feature-Erkennung ('onbeforeinstallprompt' in window) und biete als Rückfall eine manuelle Anleitung an.
prompt() darf pro Ereignisobjekt nur einmal aufgerufen werden; ein weiterer Aufruf wirft einen InvalidStateError. Nach Ablehnung feuert das Ereignis erst bei einem späteren Seitenaufruf erneut.
prompt() erfordert eine Nutzeraktivierung (z. B. Klick) – direkt im Handler aufgerufen, wird es meist blockiert.
Ist die App bereits installiert oder erfüllt die Seite die Kriterien nicht (fehlendes Manifest, kein HTTPS), feuert das Ereignis gar nicht. Zeige den Installations-Button daher erst im Handler an.
Seit Chrome 76 wird die Mini-Infobar nur noch bei Aufruf von preventDefault() unterdrückt; das Verhalten kann sich zwischen Versionen ändern.

Siehe auch

BeforeInstallPromptEvent Window: appinstalled BeforeInstallPromptEvent.prototype.prompt() Event.prototype.preventDefault() EventTarget.prototype.addEventListener() Window IDBRequest: error