I have websites in my dock on my computer. I have websites on the home screen of my phone. When I open these websites from the dock or from the home screen, they behave just like native apps. It���s brilliant!

But knowing that you can add a website to the dock or to the home screen remains arcane knowledge. If you don���t know it���s possible, most web browsers aren���t going to tell you it���s an option. As a site owner, you pretty much have to explain to your users what they can do.

Lately it feels like there���s been some movement to change this situation. Or, at the very least, there���s been some discussion.

As a site owner, what you want is a way for someone visiting your site to press a button to initiate the process of adding the site to the dock or the home screen.

From what I can see from the discussion, there are two contenders for how to do this: BeforeInstallPromptEvent versus navigator.install.

I���ve used both APIs in production, so I���d like to offer my balanced feedback on both:

To add more detail���

The BeforeInstallPromptEvent API relies on you capturing and delaying an event that may or not fire at all.

Based on some arbitrary heuristics, Chrome���for example���will prompt the user to install the current website. This easily-dismissable prompt looks indistinguishable from a prompt to sign up to a newsletter or grant permission for cookies, so most people dismiss it. The idea with BeforeInstallPromptEvent is that you capture that prompt, prevent it from prompting, and then release it when you think it���s an appropriate time.

If you think it takes mental gymnastics to understand that, just imagine what it���s like trying to implement it!

The whole thing rests on this flawed idea of an install prompt being shown when certain conditions are met. Other browser vendors rightly point out that users should be able to install any website they want. Ideally it should have a manifest file. But making a service worker a requirement is a step too far (and I say that as someone who literally wrote a book about service workers).

Contrast that with the Web Install API, AKA navigator.install.

Based on a user interaction���like a click on a button���the browser initiates the installation process. The user still has to confirm they want to do this, of course. You know how geolocation or web notifactions work? It���s like that. You can���t trigger any of those APIs without the user���s permission.

That���s it. No contest.

It would be absolutely wonderful if more browsers supported navigator.install. It would be a pain in the ass if they decided to support BeforeInstallPromptEvent instead.