search

MicrosoftEdge / MSEdgeExplainers

Home for explainer documents originated by the Microsoft Edge team
Creative Commons Attribution 4.0 International
1.29k stars 205 forks source link

[Web Install] Add an "InsufficientEngagementError" #663

Closed dfabulich closed 1 year ago

dfabulich commented 1 year ago

Chromium browsers currently gate the onbeforeinstallprompt event behind an engagement heuristic.

https://web.dev/install-criteria/

In Chrome, your Progressive Web App must meet the following criteria before it will fire the beforeinstallprompt event and show the in-browser install promotion:

  • The web app is not already installed
  • Meets the user engagement heuristics:
    • The user needs to have clicked or tapped on the page at least once (at any time, even during a previous page load)
    • The user needs to have spent at least 30 seconds viewing the page (at any time)

For a same-domain installation, if the user clicks on a button that calls navigator.install() before the 30-second timer is up, then navigator.install() needs to fail with an error in that case.

Currently the explainer documents three possible types of errors:

  • NotAllowedError: The installation Permissions Policy has been used to block the use of this feature.
  • NotSupportedError: the target website is not installable.
  • OperationError: other error.

I think we need one more, which I'm suggesting could be called InsufficientEngagementError. In that case, the installation hasn't been blocked by permissions policy; you just need the user to engage with the site a little bit more.

diekus commented 1 year ago

@dfabulich I like this. It's a valid way of making sure that n.install can't immediately start spamming installation prompts. It also gives some time for the UA to perform the required installability checks. I'll consider it, I think it can provide good feedback to devs when the loading is in this grey-area before all checks have been completed.

diekus commented 1 year ago

@dfabulich The promise will resolve if the app is installed, and will reject otherwise. One of the added errors is a InsufficientEngagementError, as you proposed. This will allow developers to know if the minimum engagement threshold has been met beforehand. Thanks for the feedback.