Signatur
Beschreibung
Die Eigenschaft userChoice des BeforeInstallPromptEvent ist ein nur lesbares Promise. Es wird erfüllt, sobald der Nutzer auf den Installationsdialog einer Progressive Web App (PWA) reagiert hat. Der Erfüllungswert ist ein Objekt mit den Eigenschaften outcome ("accepted" oder "dismissed") und platform (Kennung der Plattform, auf der installiert wurde, bei der Web-Installation meist ein leerer String "").
Üblich ist folgender Ablauf: Man fängt das Ereignis beforeinstallprompt ab, unterdrückt mit preventDefault() die automatische Mini-Infoleiste, speichert das Ereignisobjekt und ruft später – etwa bei einem Klick auf einen eigenen „App installieren“-Button – prompt() auf. Anschließend wartet man mit await event.userChoice auf die Entscheidung, um die Oberfläche anzupassen oder die Entscheidung für Statistiken zu erfassen.
userChoice gibt bei jedem Zugriff dasselbe Promise zurück. Es wird erst erfüllt, nachdem der Dialog angezeigt und beantwortet wurde. Wer nie prompt() aufruft, wartet also unter Umständen ewig. Neuere Chromium-Versionen liefern dasselbe Ergebnisobjekt auch direkt als Rückgabewert von prompt().
Rückgabewert
Promise, das mit einem Objekt erfüllt wird: outcome ist "accepted", wenn der Nutzer installiert hat, und "dismissed", wenn er den Dialog abgelehnt oder geschlossen hat. platform nennt die gewählte Plattform (bei Web-Installationen meist "").Beispiele
Eigener Installations-Button mit Auswertung der Entscheidung
let deferredPrompt = null;
const installButton = document.querySelector('#install');
installButton.hidden = true;
window.addEventListener('beforeinstallprompt', (event) => {
// Automatische Infoleiste unterdrücken
event.preventDefault();
deferredPrompt = event;
installButton.hidden = false;
});
installButton.addEventListener('click', async () => {
if (!deferredPrompt) return;
deferredPrompt.prompt();
const { outcome, platform } = await deferredPrompt.userChoice;
console.log(`Entscheidung: ${outcome} (Plattform: "${platform}")`);
// Das Ereignis lässt sich nur einmal verwenden
deferredPrompt = null;
installButton.hidden = true;
});Entscheidung für Statistiken erfassen
window.addEventListener('beforeinstallprompt', async (event) => {
event.preventDefault();
// Hier sofort anzeigen (in der Praxis besser nach einer Nutzeraktion)
document.querySelector('#install').addEventListener('click', () => event.prompt(), { once: true });
const choice = await event.userChoice;
navigator.sendBeacon('/analytics/pwa-install', JSON.stringify({
outcome: choice.outcome,
timestamp: Date.now()
}));
});Mit Feature-Erkennung und Zeitlimit absichern
const waitForChoice = (event, ms = 60_000) =>
Promise.race([
event.userChoice,
new Promise((resolve) =>
setTimeout(() => resolve({ outcome: 'timeout', platform: '' }), ms)
)
]);
if ('onbeforeinstallprompt' in window) {
window.addEventListener('beforeinstallprompt', async (event) => {
event.preventDefault();
await event.prompt();
const { outcome } = await waitForChoice(event);
console.log(outcome === 'accepted' ? 'Installiert!' : `Keine Installation (${outcome})`);
});
} else {
console.log('Installationsdialog wird von diesem Browser nicht unterstützt.');
}// Wichtig · Fallstricke
- Nicht standardisiert und experimentell:
BeforeInstallPromptEventgibt es nur in Chromium-Browsern. Firefox und Safari (auch unter iOS) unterstützen das Ereignis nicht. Prüfe die Unterstützung vorher, z. B. mit'onbeforeinstallprompt' in window, und biete sonst eine Anleitung an (etwa „Zum Home-Bildschirm“ in Safari). - Nur einmal verwendbar:
prompt()darf pro Ereignis nur einmal aufgerufen werden. Danach ist das Ereignis verbraucht. Für einen neuen Versuch musst du auf ein neuesbeforeinstallpromptwarten. - Nutzeraktion erforderlich:
prompt()muss durch eine Nutzeraktion ausgelöst werden, z. B. einen Klick. Sonst wird dasPromiseabgelehnt unduserChoicenie erfüllt. outcome === "accepted"bedeutet nur, dass der Nutzer zugestimmt hat. Ob die Installation wirklich abgeschlossen wurde, meldet zuverlässig das Ereignisappinstalledaufwindow.- Das Ereignis wird nur ausgelöst, wenn die Installationskriterien erfüllt sind: HTTPS, ein gültiges Web-App-Manifest und die App ist noch nicht installiert.