BeforeInstallPromptEvent.prompt() — Methode · JavaScript-Referenz

Signatur

BeforeInstallPromptEvent.prototype.prompt()

Beschreibung

Erfüllt eine Web-App die Installationskriterien (u. a. gültiges Web-App-Manifest, Auslieferung über HTTPS), löst ein Chromium-Browser auf window das Ereignis beforeinstallprompt aus. Ruft man darin event.preventDefault() auf, unterdrückt man die automatische Installationsleiste bzw. den Hinweis des Browsers und kann das Ereignisobjekt für später speichern. Mit prompt() zeigt man den Installationsdialog dann genau dann an, wenn es in den Ablauf der Anwendung passt – typischerweise nach einem Klick auf einen eigenen „App installieren“-Button.

Die Methode gibt ein Promise zurück, das sich erfüllt, sobald die Person im Dialog entschieden hat. Das Ergebnisobjekt enthält outcome ("accepted" oder "dismissed") und platform (die Plattform, auf der installiert wurde, bzw. einen leeren String bei Ablehnung). Dieselbe Information liefert auch die Eigenschaft userChoice des Ereignisses.

Wichtig: Jedes BeforeInstallPromptEvent kann nur einmal für prompt() verwendet werden. Danach sollte die gespeicherte Referenz verworfen werden. Wurde der Dialog abgelehnt, löst der Browser unter Umständen später erneut beforeinstallprompt aus, und erst dann ist ein neuer Aufruf möglich.

Rückgabewert

Typ

Promise<{ outcome: "accepted" | "dismissed", platform: string }>

Beschreibung

Ein Promise, das sich mit einem Objekt erfüllt: outcome gibt an, ob die Installation angenommen ("accepted") oder abgelehnt ("dismissed") wurde, platform nennt die gewählte Plattform (bei Ablehnung meist ""). Bei erneutem Aufruf auf demselben Ereignis oder fehlender Nutzeraktivierung wird das Promise mit einer DOMException abgelehnt.

Beispiele

Eigenen Installations-Button anbieten

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

window.addEventListener('beforeinstallprompt', (event) => {
  // Automatischen Browser-Hinweis unterdrücken
  event.preventDefault();
  deferredPrompt = event;
  installButton.hidden = false;
});

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

  // Muss innerhalb einer Nutzeraktion aufgerufen werden
  const { outcome, platform } = await deferredPrompt.prompt();
  console.log(`Ergebnis: ${outcome} (Plattform: ${platform || '–'})`);

  // Ereignis ist verbraucht – Referenz verwerfen
  deferredPrompt = null;
  installButton.hidden = true;
});

Ergebnis: accepted (Plattform: web)

Erfolgreiche Installation zusätzlich über appinstalled erfassen

window.addEventListener('appinstalled', () => {
  console.log('PWA wurde installiert');
  // z. B. Analyse-Ereignis senden, Installations-UI dauerhaft ausblenden
  localStorage.setItem('pwa-installed', '1');
});

PWA wurde installiert

Robuster Aufruf mit Fehlerbehandlung und Feature-Erkennung

const supportsInstallPrompt = 'onbeforeinstallprompt' in window;

const showInstallDialog = async (promptEvent) => {
  try {
    const choice = await promptEvent.prompt();
    return choice.outcome === 'accepted';
  } catch (error) {
    // InvalidStateError: bereits verwendet; NotAllowedError: keine Nutzeraktivierung
    console.warn(`Installationsdialog fehlgeschlagen: ${error.name}`);
    return false;
  }
};

if (!supportsInstallPrompt) {
  console.log('Kein beforeinstallprompt – Anleitung für manuelle Installation zeigen');
}

Kein beforeinstallprompt – Anleitung für manuelle Installation zeigen

// Wichtig · Fallstricke

Browser-Kompatibilität: BeforeInstallPromptEvent ist nicht standardisiert und nur in Chromium-basierten Browsern verfügbar. Firefox und Safari (inkl. iOS) unterstützen es nicht – dort braucht man eine eigene Anleitung (z. B. „Zum Home-Bildschirm hinzufügen“ über das Teilen-Menü).
Nur einmal pro Ereignis: Ein zweiter Aufruf von prompt() auf demselben Ereignisobjekt schlägt mit einer InvalidStateError-DOMException fehl.
Nutzeraktivierung erforderlich: Der Aufruf muss in direkter Folge einer Nutzeraktion (Klick, Tastendruck) geschehen. Wird prompt() z. B. per Timer oder direkt im beforeinstallprompt-Handler aufgerufen, kann er mit NotAllowedError abgelehnt werden.
Ohne preventDefault() im beforeinstallprompt-Handler zeigt der Browser ggf. seine eigene Installations-UI; das Ereignis lässt sich aber trotzdem speichern.
Das Ereignis wird nicht ausgelöst, wenn die App bereits installiert ist oder die Installationskriterien (Manifest, HTTPS, Icons u. a.) nicht erfüllt sind. Die Kriterien können sich zwischen Browserversionen ändern.
Nicht zu aufdringlich einsetzen: Den Dialog erst anbieten, wenn die Person Interesse an der App gezeigt hat – Ablehnungen können dazu führen, dass der Browser das Ereignis länger nicht mehr auslöst.

Siehe auch

new BeforeInstallPromptEvent() new InstallEvent() Event.preventDefault() InstallEvent.addRoutes() Fence.reportEvent()