BeforeInstallPromptEvent

[marcoscaceres]

WebKittens

@marcoscaceres @othermaciej @smfr @rniwa

Previously commented on related issues:

• Ryosuke Niwa (@rniwa) - Issue #835, PR #836
• Maciej Stachowiak (@othermaciej) - Bug 193959, PR #836
• Marcos Caceres (@marcoscaceres) - Bug 255716
• Simon Fraser (@smfr) - Bug 198673

Title of the proposal

BeforeInstallPromptEvent API (for installing the "current app")

URL to the spec

https://www.w3.org/TR/appmanifest/

URL to the spec's repository

https://github.com/w3c/manifest

Issue Tracker URL

https://github.com/w3c/manifest/issues

Explainer URL

https://pr-preview.s3.amazonaws.com/w3c/manifest/pull/1206.html#installation-events

TAG Design Review URL

No response

Mozilla standards-positions issue URL

No response

WebKit Bugzilla URL

• Bug 193959 - Original BIP request (2019, RESOLVED WONTFIX)
• Bug 255716 - Duplicate with detailed discussion (2023)
• Bug 198673 - Related: feature detection for "Add to Home Screen"

Radar URL

No response

Description

The BeforeInstallPromptEvent API enables web applications to:

1. Detect installability - Know when a web app meets installation criteria
2. Trigger native install UI - Call prompt() to open the browser's install dialog (e.g., Safari's Add to Home Screen sheet)
3. Track user response - Know whether the user accepted or dismissed the installation

How It Works

1. Once a page's manifest is processed and the page is deemed "installable" (UA-specific criteria), the browser fires beforeinstallprompt at the Window
2. The site can call event.preventDefault() to suppress any automatic browser prompt
3. The site can store the event and later call event.prompt() (requires user activation) to trigger the native install UI
4. The promise resolves with the user's choice (accepted or dismissed)

What Has Changed since BIP was removed from the Web Manifest spec

1. "When would it fire?" → Deterministically, only on pages that have an explicit manifest. And only once manifest is processed and page is installable. No complex heuristics required.
2. "Safari has no install prompt" → The event is decoupled from automatic prompts. It simply signals installability. prompt() (requiring transient user activation) can trigger Safari's existing Add to Home Screen sheet.
3. "Risk of abuse" → User activation is required for prompt(). Developers control whether to show install UI at all.

Chrome Experiment Data (Dan Murphy, Chrome team)

• Browser-native ambient UI (omnibox icon): ~0.01% CTR
• Browser-initiated blocking prompts: ~1.2% CTR
• ML targeting reduced prompt show rate by 70% with same install rate (most prompts go to uninterested users)

This data shows browser-initiated UI has very low engagement. This could support the case for developer control, or alternatively suggest most users don't want to install web apps.

Proposed User Benefits of BIP

• Users discover installability at contextually appropriate moments, not arbitrary browser-chosen times. However, this only applies if the browser shows an intrusive UI.
• Users avoid installation prompts during critical tasks (checkout, form completion, etc.). Not a concern if the browser never prompts.

User Harm from Current Workarounds

Sites resort to workarounds that harm users:

• Browser sniffing is fragile - Sites detect Safari via User-Agent and show manual installation instructions, but this breaks when UA strings change or on non-Safari WebKit browsers.
• Static screenshots become outdated - Installation instructions include screenshots of Safari's share sheet, which become incorrect when the UI changes across iOS/macOS versions
• "Add to Home Screen" moves around - The option's location in the share sheet is not consistent across platforms and browser versions, leading to user confusion when following outdated guides
• Users see wrong instructions - Combining the above, users frequently encounter installation guides showing the wrong screenshots for their Safari/iOS version

BIP eliminates this class of user-facing bugs by allowing sites to detect installability programmatically and trigger native UI directly, rather than attempting to describe ever-changing browser UI.

Web Compatibility

• BIP has shipped in Chromium-based browsers for approximately 10 years
• Sites already use it with progressive enhancement (feature detection)
• Safari users currently receive a degraded experience: static instructions instead of a functional install flow
• Standardizing the API aligns Safari with existing web reality and allows sites to provide a consistent, correct experience across browsers

[hober]

The answer to "When would it fire?" assumes that "installation" is gated on having a manifest file, which it isn't on macOS. Any webpage may be added to the Dock.

[rniwa]

I don't think we should provide a way for website to programmatically trigger a "Add to Home Screen" sheet even under a user activation. User activation almost always happens on iOS because user has to tap screen to even scroll the page.

[marcoscaceres]

I’m currently investigating previous comments folks from the WebKit community have made and will draft a history soon. It won’t be a formal position (will draft something immediately after), but I’m hoping to show that even with the recent changes to BIP, it is not a suitable solution for the problems it tried to address… and why it was removed from the spec in 2019 (based on the arguments primarily put forward by folks in the WebKit community).

[marcoscaceres]

Also clarifying the origins of this request for a position: this is a request coming from the W3C Web Apps WG members, who have been discussing this and other solutions for installing web applications recently (I.e., this is not Marcos requesting a position… I’m just the messenger).

At TPAC 2025 and on a recent working group call, it was agreed that potential implementers would seek formal implementer positions around this and related proposal. Posting this to fulfill that request from the working group.

[marcoscaceres]

Note: this response is not a WebKit position... this is just me (@marcoscaceres) gathering everything in one place so WebKit folks can formulate a position. I'm trying to distill a lot of years worth of discussions below.

Historical WebKit Feedback

Key concerns from Ryosuke Niwa @rniwa (Issue #835, 2019)

These concerns led to BIP being removed from the spec in 2020 Pull Request #836:

1. User intent signal weakening: "Prompting the user to 'install' a website makes it hard to tell whether the user actually wanted to save the website for later use, or the user just wanted to pass through the prompts encountered before using / while the web app."

2. Installation shouldn't gate features: "If we're trying to gate any feature only to installed apps, then it goes directly against the goal of differentiating websites that the user trusts; by the virtue of eagerly asking the user to install an app, we've decreased the likelihood that the user intentionally did so."

3. Users may tap through from habit: "The issue is that if website is asking the user to save it on home screen, that is less of a signal to the web browser / operating system that the user had intentionally done so because some user may just tap through prompts from habit / muscle memory."

4. Browser UI preferred over site-triggered: "If the user were to manually add it to home screen via browser's UI, then that's more of a positive signal that the user wanted to do that."

5. Upfront permission requests are problematic: "In general, we don't think asking persistent permissions upfront in a manner disassociated with the relevant user actions is a good model for security or privacy sensitive features because there is a risk for users to tap through prompts without fully understanding the implications."

Additional Bugzilla feedback

6. Maciej Stachowiak (Bug 193959, 2019): "We don't have an install prompt in Safari, either automatic or site-initiated. Unless that changes, supporting the event in WebKit wouldn't do anything because it would never fire."

7. Marcos Caceres (Bug 255716, 2023): Raised concerns about:

   • When the event would fire given Safari has no "UA-defined criteria" unlike Chrome used to have.
   • Risk of abuse if event fires for every page with a manifest

8. Simon Fraser (Bug 198673, 2019): "Pages need a way to feature-detect iOS vs desktop in order to tailor their display of 'Add to home screen' instructions, since this only applies to iOS. It's no longer possible to use the user agent string for this on iPad."

Which Concerns Remain Unaddressed

Concern	Status	Analysis
User intent signal weakening (1, 3)	Partially addressed	Transient user activation means user must click something, but they're still responding to site-initiated UI. Users could develop muscle memory for tapping through install prompts, similar to cookie banners.
Installation shouldn't gate features (2)	Tangential	BIP doesn't create feature gating - that's browser policy. However, some features (Web Push on iOS, Badging) do require installation, so installation provides a path to those features.
Browser UI preferred over site-triggered (4)	Not addressed	This is a fundamental philosophical difference. The proposal is specifically about enabling site-triggered installation. Ryosuke's position is that browser-initiated (share sheet) provides a stronger trust signal than site-initiated.
Upfront permission requests (5)	Not directly applicable	BIP itself doesn't grant permissions - installation just provides home screen placement and standalone mode. However, if sites combine installation prompts with permission requests, the pattern remains.

[slightlyoff]

Apologies for the drive-by comments. There seem to be some misconceptions in this thread. I'll try to address them in chronological order.

@hober: your concern is valid, but also subject to UA-specific choices. Chromium-based browsers, for example, have supported both modes of installation, with a "tall enough to ride the ride" bar gating UA-provided prompts (such as banners, ala Smart Banners) and affordances such as the "install" chips that show in the URL bar. oBIP is only delivered in Chromium browsers when the bar is passed. Sites that haven't met this bar are still globally installable from menu-driven actions by users, but the event is not dispatched.

It's a decision for each UA to decide if/when to send the event, and as with banners and other affordances, it's contingent and asynchronous to allow browsers to suppress spammy behaviour and deny bad actors extra promotion. It's compatible with the design of the event for Safari to trigger the event on all pages, only some pages, or only some pages when other criteria are met. Nothing about the API forces one decision or another.

This mirrors the policy flexibility that was designed into many other permission-gated APIs such as Push Notifications, where Safari's decision to provide access only to installed apps is different to other browsers as a result of the space explicitly designed into the spec to enable per-UA policy choices to differ.

@rniwa: while it's possible for the API to directly install without other interaction, that's not the flow on any other browser I'm aware of. Instead, oBIP installation clicks tend to invoke browser-provided dialogs and affordances (from trusted UI) that give users choices. Combined with policy choices a UA makes (per the previous response), the idea is that this gives users affirmative understanding of what is being proposed for installation and control over the process. Apologies if this wasn't clear, although you should be able to see the flow in Chromium-based browsers today.

@marcoscaceres: on the question of feature gating, this again falls into a policy choice that Safari can make, and which is entirely compatible with the explicit design of permission-gated APIs. We (Chromium) don't presume to know what the final answer to these questions are, and have made many adjustments over the years since these features launched, including reducing prompt spam through service-driven reputation checks and alignment with gates around requiring, e.g., TLS. Gating on installation is one such policy, and not different in spirit to others. I don't think it reads on this API one way or another, only the choices Safari would make in implementing it.

As for browser UI vs. site triggering, please see my response above to @rniwa. There has been explicit work put into these flows to ensure UAs can keep users in the driver's seat, and if there's missing space to implement whatever design you think best, would welcome comment on what that might be.

Best,

Alex

[marcoscaceres]

Thanks @slightlyoff! really appreciate the detailed context. We’re continuing to discuss the architectural questions around installation and user intent signals, and will follow up once we’ve refined our position.

[mtom55]

The ability to easily install web apps is the single biggest barrier preventing web apps (and the mobile web) from succeeding. Without a simple, visible, and frictionless installation path, web apps are effectively neuted, no matter how capable the underlying technology becomes. This also needs to be compared to the native app installation path, with a solution that is equivalent in ease of use.

[marcoscaceres]

Thanks for raising this perspective, @mtom55.

The discussion here is primarily about whether the platform should expose BIP to allow sites to initiate installation flows. Questions about how visible or easy installation should be through browser UI are related, but slightly different.

WebKit is still finalizing its position on BIP, and we’ll be publishing that shortly. That position will try to explain the architectural considerations that inform our thinking here.

[hunterirving]

First off, thank you to everyone involved for spending the time to carefully consider this issue.

I develop and distribute several web apps, and currently point users to this static installation guide: https://hunterirving.github.io/web_workshop/pages/pwa/

As the opening comment in this thread makes clear:

• Static screenshots become outdated - Installation instructions include screenshots of Safari's share sheet, which become incorrect when the UI changes across iOS/macOS versions
• "Add to Home Screen" moves around - The option's location in the share sheet is not consistent across platforms and browser versions, leading to user confusion when following outdated guides
• Users see wrong instructions - Combining the above, users frequently encounter installation guides showing the wrong screenshots for their Safari/iOS version

Additionally, as my installation guide demonstrates, it takes iOS users six highly unlikely interactions to install a web app to their homescreen, one of which requires vertically scrolling an area that gives no visual indication it is scrollable (step 4). I realize this is a Safari UI issue and not a WebKit issue, but I think it illustrates the reality of the installation experience today's end users must contend with.

Though web app installation is technically supported, the installation process is so esoteric that very few users will ever:

• realize apps can be installed from a web browser
• realize a given website can be installed as a web app
• make it through the labyrinthine installation process to install one

Support for BIP (or something like it), would alleviate all of the issues outlined above.

One final statement from the original comment that I'd like to gently push back on:

This data shows browser-initiated UI has very low engagement. This could support the case for developer control, or alternatively suggest most users don't want to install web apps.

I believe it is much more likely that engagement is low because public awareness of web apps is low, due in large part to the fact that today's installation flows are lacking.

Thanks again for considering this issue - the developer community is rooting for you!

[trcrsired]

Hello. I am the author of the PWA Store (which is listed on microsoft store now).
https://pwa-store-7x5.pages.dev

Microsoft edge recently added an experimental webinstall api that allows the PWA stores to install pwas through the store itself. However, I have tried web install api simply does not work for most websites even it supports it. Things like cloudflare block installation.