new BeforeInstallPromptEvent() — Methode · JavaScript-Referenz

Signatur

new BeforeInstallPromptEvent(type, options)

Beschreibung

Der Konstruktor BeforeInstallPromptEvent() erzeugt ein neues Ereignisobjekt vom Typ BeforeInstallPromptEvent. Im Normalfall erzeugt der Browser selbst dieses Ereignis und löst es als beforeinstallprompt auf window aus, sobald eine Progressive Web App (PWA) die Installationskriterien erfüllt (Web-App-Manifest, Service Worker, HTTPS usw.).

Den Konstruktor selbst aufzurufen ist vor allem für Tests und Simulationen sinnvoll: Du kannst damit prüfen, ob dein eigener Handler das Ereignis korrekt abfängt, preventDefault() aufruft, das Objekt für später speichert und z. B. einen eigenen „App installieren“-Button einblendet – ohne auf die echte Installationsbereitschaft des Browsers warten zu müssen.

Wichtig: Ein selbst erzeugtes Ereignis ist nicht mit dem Installationsmechanismus des Browsers verknüpft. Ein Aufruf von prompt() an einem synthetischen Ereignis zeigt keinen echten Installationsdialog an. Außerdem ist isTrusted bei solchen Ereignissen immer false.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Für den echten Anwendungsfall ist das `"beforeinstallprompt"`.
$options	Object	{}	Optionales Objekt, das neben den Feldern aus `EventInit` (`bubbles`, `cancelable`, `composed`) folgende Eigenschaft unterstützt: `platforms` (`string[]`, Standard `[]`): Liste der Plattformen, auf denen installiert werden kann, z. B. `["web"]`. Wird über die Eigenschaft `platforms` ausgelesen. Ältere Dokumentationen nennen zusätzlich `userChoice`; diese Option wird von aktuellen Chromium-Versionen jedoch nicht übernommen.

Rückgabewert

Typ

BeforeInstallPromptEvent

Beschreibung

Ein neues BeforeInstallPromptEvent-Objekt, das per dispatchEvent() ausgelöst werden kann.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

if ('BeforeInstallPromptEvent' in window) {
  const event = new BeforeInstallPromptEvent('beforeinstallprompt', {
    cancelable: true,
    platforms: ['web']
  });

  console.log(event.type);
  console.log(event.platforms);
  console.log(event.isTrusted);
} else {
  console.log('BeforeInstallPromptEvent wird nicht unterstützt');
}

beforeinstallprompt ['web'] false

Eigenen Install-Handler im Test auslösen

let deferredPrompt = null;
const installButton = document.createElement('button');
installButton.textContent = 'App installieren';
installButton.hidden = true;
document.body.append(installButton);

window.addEventListener('beforeinstallprompt', (event) => {
  event.preventDefault();      // Browser-Mini-Infoleiste unterdrücken
  deferredPrompt = event;      // für später merken
  installButton.hidden = false;
  console.log('Install-Button eingeblendet');
});

// Simulation, z. B. in einem Integrationstest
const fakeEvent = new BeforeInstallPromptEvent('beforeinstallprompt', {
  cancelable: true,
  platforms: ['web']
});
window.dispatchEvent(fakeEvent);

console.log(deferredPrompt === fakeEvent, installButton.hidden);

Install-Button eingeblendet true false

Echtes vs. synthetisches Ereignis unterscheiden

window.addEventListener('beforeinstallprompt', async (event) => {
  event.preventDefault();

  if (!event.isTrusted) {
    console.log('Synthetisches Ereignis – kein echter Dialog möglich');
    return;
  }

  await event.prompt();
  const { outcome } = await event.userChoice;
  console.log(`Nutzerentscheidung: ${outcome}`);
});

window.dispatchEvent(
  new BeforeInstallPromptEvent('beforeinstallprompt', { cancelable: true })
);

Synthetisches Ereignis – kein echter Dialog möglich

// Wichtig · Fallstricke

Nicht standardisiert und experimentell: BeforeInstallPromptEvent gibt es nur in Chromium-basierten Browsern. Firefox und Safari kennen weder das Ereignis noch den Konstruktor. Prüfe vorher mit 'BeforeInstallPromptEvent' in window, ob es vorhanden ist, sonst wirft der Aufruf einen ReferenceError.
Kein echter Installationsdialog: Selbst erzeugte Ereignisse sind nicht mit dem Browser verknüpft. prompt() zeigt dabei keinen Dialog an (das Promise wird in der Regel abgelehnt), und userChoice wird nicht sinnvoll erfüllt. Nutze den Konstruktor also nur für Tests.
cancelable: true setzen, wenn dein Handler preventDefault() aufruft. Sonst bleibt defaultPrevented im Test false.
In TypeScript fehlt der Typ in lib.dom.d.ts, du musst ihn selbst deklarieren.

Siehe auch

new ExtendableEvent() new InstallEvent() new FormDataEvent() new InterestEvent() new MediaStreamEvent()