[w3c/manifest] Clarify circumstances in which BeforeInstallPromptEvent.prompt() may be called (#691)

Currently a few issues:

1. Chrome requires prompt() to be called on user gesture. This isn't in the spec. We did this to check  Is this something we can just require in the spec, or can we say that the user agent MAY require a user gesture?
2. Neither Chrome nor the spec requires preventDefault() to be called before prompt(). Consider this code (assuming the #install_app button is disabled on load):

```js
addEventListener('beforeinstallprompt', e => {
  document.querySelector('#install_app').disabled = false;
  stashed_bip = e;
});

document.querySelector('#install_app').addEventListener('click', async () => {
  console.log(await stashed_bip.prompt());
});
```

It doesn't call `preventDefault`, which means if you have a standards-compliant browser that shows an automated prompt, the above code works this way:

1. The UA fires the `beforeinstallprompt` event.
2. The `beforeinstallprompt` event handler enables the "Install" button.
3. The UA shows an automated prompt, and the user accepts or dismisses it.
4. The user clicks the still-active "Install" button.
5. `prompt()` immediately resolves with the result of the automated install banner, without showing a second prompt.

This is a bad user experience because they are left with an enabled, but ineffective Install button.

However, the above code runs perfectly well in a browser that does not use automated install prompts, such as Chrome.

Suggested changes:

1. Require a user gesture for `prompt()`. (Are there any UAs that implement `BeforeInstallPromptEvent.prompt()` that don't require a user gesture?)
2. I think we need to disassociate the automated install prompt with BeforeInstallPromptEvent. UAs are still allowed to show an automated install prompt, and may fire BIP at the same time as showing the automated prompt. But calling `prompt()` from inside BIP would require the UA to show a second prompt, even if an automated one was already shown. `prompt()` wouldn't just return the result of the previously-shown automated prompt. You would still be able to use `preventDefault` to cancel *some* automated prompts (see below). There would be no need to use `preventDefault` before calling `prompt`, but sites may still wish to do this.

This gives UAs a couple of options:

1. Don't ever show an automated prompt. Require the developer to use `prompt` to show a prompt.
2. Show some automatic or ambient prompt to install, but don't consider it related to BIP at all. This prompt could have a totally different (e.g., much more subtle) UI than the full prompt triggered by `prompt`, e.g., it could be a thin banner or a button next to the URL bar. From a spec perspective, this is exactly the same as Option 1; the "automated prompt" is really just a piece of browser UI for installing the app, just like an "add to home screen" menu item. This is the approach we are currently taking with Chrome, and it fits Firefox's current prompting model as well. Fire BIP at any time (doesn't have to be the same time as showing the automated prompt), and respect its `prompt`. `preventDefault` would have no impact on the automated prompt (since it is shown independently of BIP).
3. Show a prompt and fire BIP at the same time. `preventDefault` would stop the automatic prompt from firing. However, if the UA does this, it must allow `prompt()` to show a second prompt if the user dismissed the automated one or if installation failed. As a UA, don't choose Option 3 if you don't want the second prompt to be triggerable.
4. Show an automated prompt, and do not fire BIP at all. This is Firefox's current approach, I believe.

The above suggestion, I believe, will be compatible with Chrome and Firefox today, and avoid the awkward compat issue with any future browsers (or old versions of Chrome) highlighted above.

@jungkees does Samsung Browser behave in a way compatible with the described changes?

@dominickng @marcoscaceres @kenchris 

(I can rework the described changes in the form of a pull request if it's unclear.)

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/issues/691