A PWA (Progressive Web App) install prompt is a browser-generated UI that invites users to add a web application to their device's home screen. It appears when the browser determines that the website meets PWA installability criteria — including a valid manifest, registered service worker, HTTPS, and sufficient user engagement. Once installed, the PWA launches in a standalone window, providing a native app-like experience with offline capabilities and push notifications.

Core requirements:

• HTTPS: The site must be served over a secure connection (localhost is exempt for development).
• Valid Web App Manifest: A manifest.json file linked with <link rel="manifest">, containing at minimum name or short_name, start_url, display (standalone/fullscreen/minimal-ui), and icons (at least 192x192 and 512x512 pixels).
• Registered Service Worker: A functional service worker with a fetch handler must be registered and active.
• User Engagement: Chrome requires the user to interact with the site meaningfully before showing the prompt.

Common reasons the install prompt may not appear:

• Missing or invalid manifest: Ensure all required fields are present and the manifest is valid JSON.
• Service worker not registered: Verify the SW is registered, activated, and includes a fetch handler.
• Icons too small: Chrome requires at least a 192x192 icon; some browsers need 512x512.
• User previously dismissed: If the user dismissed the prompt, there's a cooldown period (typically ~3 months in Chrome).
• Already installed: The prompt won't show if the PWA is already installed or running in standalone mode.
• Low engagement: The user hasn't interacted enough with the page yet.

The beforeinstallprompt event is fired by the browser when a PWA meets all installability criteria. Developers can listen for this event to:

• Defer the prompt: Save the event and trigger it later with event.prompt() at a custom UI element.
• Track user choice: Use event.userChoice to see if the user accepted or dismissed the prompt.
• Custom timing: Show the install prompt at an opportune moment rather than when the browser decides.

Note: You cannot manually trigger this event — it's browser-initiated. The recommended pattern is to capture it and use it with a custom install button.

While the browser's default install prompt UI cannot be fully customized, you can influence its content through your manifest:

• App name & short name: Set in manifest.json — the short name appears under the icon.
• App icon: The browser uses your manifest icons; ensure they're high-quality.
• Description: Some browsers display the description field.
• Custom install flow: Capture beforeinstallprompt and trigger it from your own UI button for a branded experience.
• Screenshots: On Android, rich install dialogs can include screenshots defined in the manifest.

Full PWA install support:

• Google Chrome (Android & Desktop) — Full support with beforeinstallprompt event.
• Microsoft Edge (Android & Desktop) — Full support, Chromium-based.
• Samsung Internet (Android) — Full support.
• Opera (Android & Desktop) — Supported on most versions.
• Firefox (Android) — Partial support; desktop version has limited PWA install.
• Safari (iOS/iPadOS) — PWA install is supported via "Add to Home Screen" in the Share menu, but no beforeinstallprompt event. Requires Apple-specific meta tags.

You can track PWA install events using several methods:

• beforeinstallprompt: Log when the event fires to measure eligibility rates.
• userChoice: After calling event.prompt(), check event.userChoice.outcome for 'accepted' or 'dismissed'.
• appinstalled event: Listen for the appinstalled event to detect successful installations.
• display-mode media query: Use matchMedia('(display-mode: standalone)') to detect if users are launching in PWA mode.
• Google Analytics / GA4: Send custom events for each step of the install funnel.

In Chrome, if a user dismisses or cancels the PWA install prompt, the browser imposes a cooldown period of approximately 3 months before the beforeinstallprompt event will fire again for that site. During this period, no automatic prompt will appear. However, the user can still manually install the PWA through the browser menu (⋮ → "Install app" or "Add to Home screen"). The cooldown is per-origin and helps prevent annoying users with repeated prompts.

Testing methods:

• Chrome DevTools: Go to Application → Manifest → click "Install" to trigger installation manually.
• Lighthouse Audit: Run a PWA audit to check if your site meets all installability criteria.
• Use this simulator: Test the visual appearance and flow of install prompts across different browser styles.
• localhost testing: Develop on localhost to bypass the HTTPS requirement during development.
• Chrome flags: Enable chrome://flags/#enable-site-engagement related flags to adjust engagement thresholds for testing.
• Android device testing: Use remote debugging with a physical Android device for the most accurate results.