Bug 255716 – Feature request: Implement `BeforeInstallPrompt` event for programmatic Add to Home Screen

• Component: New Bugs
• Status: RESOLVED DUPLICATE

[Thomas Steiner]

Triggering programmatic installation is a frequently brought forward request from app developers [1]. The `BeforeInstallPrompt` event [2] implemented in Chrome is commonly referred to as a decent way to achieve this. Now that iOS/iPadOS put more emphasis on installation (by implementing the Push and Badging APIs), it would be great if this feature were more discoverable.  

——
[1] https://docs.google.com/document/d/1chkEulpKBNQQfGIgTfQSbJhjw5mtZhvE47PF4tyTEXc/edit#heading=h.92nh0jecaouv
[2] `BeforeInstallPrompt` event: https://wicg.github.io/manifest-incubations/#beforeinstallpromptevent-interface

Related bug: https://bugs.webkit.org/show_bug.cgi?id=198673)

[Marcos Caceres]

Safari does not show an install prompt, so when would this event fire? M

[Nicolas Hoizey]

I guess Thomas is asking for programmatic installation, and `BeforeInstallPrompt` is a way to do it, but the ability to build our own UX for installation in our pages is the real need.

[Thomas Steiner]

It's actually independent of whether the browser would auto-prompt for installation. The way people would use this like so:

```js
// The install button, hidden by default.
import { installButton } from './domrefs.js';

// Variable to stash a reference to the event.
let installEvent = null;

// When UA-defined criteria are met, the UA fires this event.
// For example, when the UA detects a sufficiently complete
// manifest exists. The code now stashes the event and shows
// UI to the user, so they can manually trigger installation.
window.addEventListener('beforeinstallprompt', (event) => {
  event.preventDefault();
  installEvent = event;
  installButton.style.display = 'flex';
});

// When the install button is clicked, trigger the actual
// installation procedure (on iOS, the Add to Home Screen
// flow). The user can still cancel here, so hide or not the
// button, depending on the outcome.
installButton.addEventListener('click', async () => {
  if (!installEvent) {
    return;
  }
  installEvent.prompt();
  const result = await installEvent.userChoice;
  if (result.outcome === 'accepted') {
    installButton.style.display = 'none';
    installEvent = null;
  }
});

// After the app is installed, hide the button again.
window.addEventListener('appinstalled', (event) => {
  installButton.style.display = 'none';
  installEvent = null;
});
```

[Marcos Caceres]

Wait, what “UA-defined criteria are met”? 

In Safari, users are free to add *any* website to their Home Screen whenever they like. There is no arbitrary ever-shifting “UA criteria” in Webkit for when users can add things to the Home Screen as installed apps (sites don’t need a well-formed manifest, specific icon sizes, a service worker, or an ever changing list of arbitrary requirements). 

This is what I’m eluding to: Chrome has made some choices about “UA criteria” that we are not going to replicate in WebKit. It’s also why “installabilty signals” were removed from the Web Manifest spec (they don’t make sense or are left up to each browser if they want to go down that route, as Chrome did). 

Safari doesn’t shows an prompt, so install buttons don’t make sense. To add a web app to the home screen, the user goes to the share menu and add it from there. 

So again, I don’t see how beforeinstallprompt helps when the is literally no install prompt (and definitely no “UA-defined criteria”)?

[Thomas Steiner]

Created attachment 466006 [details]
Add to Home Screen prompt

[Thomas Steiner]

Well, Safari's criterion for triggering this prompt event is then just `if (true) {}`. Decouple your thinking from Chrome's implementation. Safari's would always `preventDefault()` and let the developer trigger the dialog (prompt) manually. When the user clicks the HTML button, the app would jump straight into the state shown at https://bugs.webkit.org/attachment.cgi?id=466006.

[Marcos Caceres]

(In reply to Thomas Steiner from comment #6)
> Well, Safari's criterion for triggering this prompt event is then just `if
> (true) {}`. Decouple your thinking from Chrome's implementation. Safari's
> would always `preventDefault()` and let the developer trigger the dialog
> (prompt) manually. When the user clicks the HTML button, the app would jump
> straight into the state shown at
> https://bugs.webkit.org/attachment.cgi?id=466006.

Right, let’s game this out: say then this event fires after a few seconds in *every single web page* (as they all meet the “UA-criteria” now). 

Suddenly every site is popping over the install sheet when a user clicks on anything (because now they can call .prompt() with almost zero cost). 

So, even if there good actors with nice install buttons, it would be rife for abuse (as we’ve seen with other permission prompts).

[Thomas Steiner]

Sure, but do people game, say, the Fullscreen API (on Safari desktop or iPad)? Any user gesture can trigger full screen, and yet people don't do this. It's generally not been a problem on Chrome. By the way, Chrome is even lowering the firing criteria, so you no longer need to be offline-capable. Instead of `if (true)`, you could of course require more strict criteria, like having a nice manifest—and people can still go through the manual flow to install any and all webpages to their device's Home Screen.

[Nicolas Hoizey]

The main issue IMHO is that many iOS Safari users don't know at all that “To add a web app to the home screen, the user goes to the share menu and add it from there”.

I get why webkit is reluctant to adding the `beforeinstallprompt` event, or allowing the `prompt()` without constraints, because there would be abuses, like with notifications and other APIs.

But at least there should be an easier way than the share sheet for people to know that web sites can be added to the homescreen. This is not a “sharing” action at all.

[Marcos Caceres]

(In reply to Nicolas Hoizey from comment #9)
> The main issue IMHO is that many iOS Safari users don't know at all that “To
> add a web app to the home screen, the user goes to the share menu and add it
> from there”.

Just noting that WebKit is not Safari, so I can’t confirm if that’s been tge Safari team’s experience. I will take this feedback to the Safari team though. 

> I get why webkit is reluctant to adding the `beforeinstallprompt` event, or
> allowing the `prompt()` without constraints, because there would be abuses,
> like with notifications and other APIs.
> 
> But at least there should be an easier way than the share sheet for people
> to know that web sites can be added to the homescreen. This is not a
> “sharing” action at all.

That’s a fair statement and something I will share this feedback internally with the Safari team that own the share sheet. 

If the UI was improved and/or users became more aware of how to add to Home Screen, do you agree there would be no limited need for BIP?

[Nicolas Hoizey]

(In reply to Marcos Caceres from comment #10)
> Just noting that WebKit is not Safari

Fair point.

> so I can’t confirm if that’s been tge
> Safari team’s experience. I will take this feedback to the Safari team
> though. 

Thanks.

I'm giving talks and trainings about PWAs to tech people, and even those of them with iPhones are often not aware of this feature.
 
> > But at least there should be an easier way than the share sheet for people
> > to know that web sites can be added to the homescreen. This is not a
> > “sharing” action at all.
> 
> That’s a fair statement and something I will share this feedback internally
> with the Safari team that own the share sheet. 
> 
> If the UI was improved and/or users became more aware of how to add to Home
> Screen, do you agree there would be no limited need for BIP?

I even agree we don't need any BIP at all, whatever the other enhancements, looking at how Chrome(ium?) made it almost instant now anyway.

However, it would be great if we could provide a way for developers to trigger the UA-provided install UI and a property to know if it makes sense right now to add content and a button in the page for this feature.

Like `Notification.permission` tells us if the user already granted/denied notifications (or didn't yet), `AddToHomeScreen.possible` would tell us if A2HS is possible (not already added to home screen for example, and Chrome could add constrainsts about Manifest values).

And like `Notification.requestPermission()` allows asking the user for such permission, `AddToHomeScreen.requestPermission()` (and a user gesture) would trigger the UA-provided install UI (the same that would be triggered by the ambiant badging icon/button and A2HS in the share sheet).

[Nicolas Hoizey]

After reading both again, I feel like latest comments here belong to https://bugs.webkit.org/show_bug.cgi?id=198673

Should I copy/paste them there?

[Marcos Caceres]

Possible duplicate of https://bugs.webkit.org/show_bug.cgi?id=193959

[Thomas Steiner]

Realizing that the feature was already requested in 2019 by, erm, a guy with the same name than mine. That's a fun coincidence! Here's the duplicate bug: https://bugs.webkit.org/show_bug.cgi?id=193959. (Sorry, I have the brain of a gold fish. Apologies!)

*** This bug has been marked as a duplicate of bug 193959 ***