Bug 198673 – Need to way to feature-detect for "Add to home screen" instructions

• Component: WebKit Misc.
• Status: NEW

[Simon Fraser (smfr)]

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.

[Radar WebKit Bug Importer]

<rdar://problem/51529870>

[Maximiliano Firtman]

Many apps add manual instructions to users to how to Add to the Homescreen (aka Install) web apps. This is more important on apps using a Web App Manifest with display: standalone (formerly apple-mobile-web-app-capable meta tag) as there is no badge, indication, banner or way for the user to know the web app can be installed as . a standalone home screen webapp. Examples of these instructions webapps are rendering are:
https://dockyard.com/blog/2017/09/27/encouraging-pwa-installation-on-ios
https://github.com/cubiq/add-to-homescreen

These apps are now using user agent sniffing to know if it's an iPhone or iPad and show proper instructions. That won't be possible on Safari on iPad OS on desktop content mode. 

One solution to the problem is to implement the beforeinstallprompt event in the Web App Manifest spec (https://www.w3.org/TR/appmanifest/#installation-events) to trigger the Share Sheet > Add to homescreen dialog that will remove the need for these instructions.

[Brent Fulgham]

This is actually:
<rdar://51410025>

Another reason why this bug is so important to fix: (On iOS at least) SFSafariViewController now uses the exact same user agent as the Safari App, but only the Safari App has "Add to Home Screen."

This makes user messaging incredibly difficult, as sometimes the "share" menu has "Add to Home Screen" and sometimes it doesn't.

Two ways forward:

 1. Add "Add to Home Screen" option to the share menu of SFSafariViewController
 2. Implement beforeinstallprompt (As a web developer, I really enjoy using this API on Android, it provides an intuitive, unobtrusive way to help the user add a web app to their home screen.)

[Thomas Steiner]

Just created a separate bug with a feature request for implementing `BeforeInstallPrompt`: https://bugs.webkit.org/show_bug.cgi?id=255716.

[Marcos Caceres]

I get sites want to have instructions, but adding them has never made sense because every UA is different and they are free to change with every release. Does your website also provide instructions for how to bookmark? 

Like many other browsers, Safari doesn’t “prompt” users in the way Chrome’s UI does, so the event doesn’t make sense. This is a situation that affects Chrome, unlike Safari, they show a prompt. 

Consider that even if the event was available, the instructions could be out of date any time a browser updates. This problem has been known for years, is well documented, and why Firefox, WebKit, and even previous incarnations of Opera rejected the event from the W3C Manifest Spec. 

Now, I’m not saying something doesn’t need to be done here, but beforeinstallprompt is not the solution to this. Or, at least, I can’t see how the event itself helps *when there is no prompt*. 

Trusting that users can figure out on their own how to “Add to Home Screen” is totally ok. The last thing we would want on website is arrows (wrongly) pointing to random parts of the browser UI to “go here ➡️➡️➡️🔝 to install”. So even if we did prompt, providing instructions would still be bad practice.

[Thomas Steiner]

Created attachment 466005 [details]
Add to Home Screen prompt

The way I envision this to work would be that clicking the developer-provided "Install" button would open the A2HS dialog (prompt) as per the attached screenshot. I think this would make a lot of sense, and the UA can at any point decide how it presents this dialog, for example, it could add screenshots to it.

[Marcos Caceres]

(In reply to Thomas Steiner from comment #7)
> Created attachment 466005 [details]
> Add to Home Screen prompt
> 
> The way I envision this to work would be that clicking the
> developer-provided "Install" button would open the A2HS dialog (prompt) as
> per the attached screenshot. I think this would make a lot of sense, and the
> UA can at any point decide how it presents this dialog, for example, it
> could add screenshots to it.

I understand, but you are presupposing that the Safari team hasn’t already given this a lot of thought (and rejected it, in the same way other browsers did!). BIP is not new! It’s like 10 years old and everyone here is well aware of it (along with all BIPs own issues, drawbacks, and trade-offs).

How Safari supports adding web apps to the Home Screen (via the share sheet) is designed to meet Safari’s user’s needs.

[Thomas Steiner]

Quite the opposite, actually. I’m sure your team have given this extensive thoughts over the past years. With A2HS becoming waaay more interesting since the newly exposed Push API (and to a lesser extent the Badging API, too), I hope the thinking can be recommenced, now that that completely new arguments have appeared.

[Marcos Caceres]

(In reply to Thomas Steiner from comment #9)
> Quite the opposite, actually. I’m sure your team have given this extensive
> thoughts over the past years. With A2HS becoming waaay more interesting
> since the newly exposed Push API (and to a lesser extent the Badging API,
> too), I hope the thinking can be recommenced, now that that completely new
> arguments have appeared.

Absolutely. Everyone is striving to improve things for users and developers. Having BIP as a possible solution if needed is great, but it’s just one of many possibilities. 

Respectfully, the Safari team does appreciate constructive feedback, but they also very much know what they are doing in this space.

[Thomas Steiner]

> Absolutely. Everyone is striving to improve things for users and developers. Having BIP as a possible solution if needed is great, but it’s just one of many possibilities. 

(1) The developer ask in https://bugs.webkit.org/show_bug.cgi?id=255716 is for a programmatic way to let users install your app.

(2) This is distinct from the expressed in https://bugs.webkit.org/show_bug.cgi?id=198673 desire to make the current Safari behavior detectable or more discoverable.

`BeforeInstallPrompt` currently fulfills the needs for (1). Max' comment https://bugs.webkit.org/show_bug.cgi?id=198673#c2 brought `BeforeInstallPrompt` into the game for (2), but as expressed above, they're two things, albeit kind of related things.

If we aren't happy with the way `BeforeInstallPrompt` fulfills (1), then maybe let's discuss alternatives. In a toot https://toot.cafe/@tomayac/110231078898885161, I hinted at `navigator.install()` or whatever. I think the use case (providing a programmatic way to let users install your app) is valid. Does Safari agree on the use case?

> Respectfully, the Safari team does appreciate constructive feedback, but they also very much know what they are doing in this space.

No doubt y'all do :-)

[Marcos Caceres]

(In reply to Thomas Steiner from comment #11)
> 
> If we aren't happy with the way `BeforeInstallPrompt` fulfills (1), then
> maybe let's discuss alternatives. In a toot
> https://toot.cafe/@tomayac/110231078898885161,

The right place to discuss alternatives is either at the w3c, as part of manifest, or in the WICG’s manifest incubations repo. Happy to pick this up there. 

> I hinted at
> `navigator.install()` or whatever. I think the use case (providing a
> programmatic way to let users install your app) is valid. Does Safari agree
> on the use case?

I can only speak for my self (and again, this is WebKit’s bug tracker, not Safari), but I don’t agree with the use case because the UI provided is (or could conceivably be made) sufficient so to obliterate the need for BIP or any .install() method. Same as we don’t have a .bookmark() method, because users know how to bookmark sites without sites needing custom bookmark banners + instructions. 

However, if you’d like a WebKit standards position on BIP, I kindly ask you file one: https://github.com/WebKit/standards-positions/issues.

[Maximiliano Firtman]

(In reply to Marcos Caceres from comment #12)
> (In reply to Thomas Steiner from comment #11)
> > 
> > If we aren't happy with the way `BeforeInstallPrompt` fulfills (1), then
> > maybe let's discuss alternatives. In a toot
> > https://toot.cafe/@tomayac/110231078898885161,
> 
> The right place to discuss alternatives is either at the w3c, as part of
> manifest, or in the WICG’s manifest incubations repo. Happy to pick this up
> there. 
> 
> > I hinted at
> > `navigator.install()` or whatever. I think the use case (providing a
> > programmatic way to let users install your app) is valid. Does Safari agree
> > on the use case?
> 
> I can only speak for my self (and again, this is WebKit’s bug tracker, not
> Safari), but I don’t agree with the use case because the UI provided is (or
> could conceivably be made) sufficient so to obliterate the need for BIP or
> any .install() method. Same as we don’t have a .bookmark() method, because
> users know how to bookmark sites without sites needing custom bookmark
> banners + instructions. 
> 
> However, if you’d like a WebKit standards position on BIP, I kindly ask you
> file one: https://github.com/WebKit/standards-positions/issues.

It's been a while since my comment in this thread. So here is my position on this matter today. 

TL;DR: The bookmark sample doesn't count as a comparison because you always get the same result when you bookmark a URL. When you add a site to the home screen on iOS and iPadOS, you get a different result on different occasions; there is no reliability in the final experience.


I don't want to comment on specs or standards; it's not my expertise; you know better than me where to discuss and how. I know this is also a WebKit forum, not a Safari discussion. However, when deciding what to implement or not, I understand use cases and UX issues for users should be a priority. 

Today's situation is a UX issue for users, not if one API is good or bad. I'm unhappy with BIP, but it's better than nothing when the browser doesn't assist the user. 

You may say the API is unnecessary, and you may be correct. Still, we are all asking for it because Safari needs to be helping with the user experience on iOS and iPadOS specifically and it's not doing it. A Safari UX change will reduce developers asking for an API whenever possible. And you are right; that's Safari, not WebKit. 

A user will never know what will happen after using "Add to Homescreen." Sometimes it's an icon opening Safari with a URL; sometimes, it's a standalone app. That standalone app has an entirely different behavior, such as using isolated storage. It also now enables more abilities, such as Web Push and Badging, two APIs WebKit implemented when Safari decided to have them on iOS and iPadOS. 

Therefore, Safari on iOS and iPadOS is implementing Web Push but with a great catch when the users will never know when a URL can provide that enhanced experience. It is an obscure antipattern for users. 

Because of it, Safari is pushing web developers to tell the users that adding this URL to the home screen will give them that enhanced experience. And I can tell as a user that it's still an unreliable experience. I've found myself adding web apps to the home screen where for some reason, the manifest wasn't parsed correctly or in time, and then I've got a shortcut web icon to Safari or a standalone icon with the wrong icon. As a user, you don't know that before opening the icon for the first time. A Safari badge, menu change, or an API delivered from WebKit if Safari doesn't want to do it can help to increase the opportunity to have the expected user experience. "This webapp is ready for ATH".

Having a way to tell if the current web app is going to install a Safari shortcut or a standalone app is essential for the author if Safari is not doing that. Even with other browsers not implementing BIP, Safari is the only browser not showing a hint, an icon, a flag, or a simple label change in the menu when the current URL is "added" as a standalone app.

It's important to understand the complete picture, the context, use cases and UX issues. Devs asking for this is not just based on a whim. You are not Safari, but you are pretty close to them :)

[Adriana Jara]

I am interested here in the comparison between add to homescreen and bookmarks, and how browsers never saw the need to add the .bookmark() api, seems to me that developers never saw an incentive to ask for such API, but they have gone to great lengths to have instructions and a way to guide users to add to homescreen, they probably see a greater interaction from users that add to homescreen than from users that create bookmarks.

We don't see incentives to create bookmarks in web sites in general, but we do see incentives to go visit the app store and get their apps also, this too shows that the use case is different and that developers are interested in having this functionality for web apps. Might even be the reason they created a web app, the ability to acquire users directly a click away. 

I'm not advocating for the BIP mechanics, I'm advocating for not shutting down the idea of developers being able to trigger an installation (after a user gesture), just because something that works technically similar in the browsers (bookmarking) didn't have such interest from developers, and because the first iteration (BIP) that was experimented with in Chromium maybe wasn't the best approach.

[Nicolas Hoizey]

(Copy/pasting part of a comment I made on https://bugs.webkit.org/show_bug.cgi?id=255716 which is now closed.)

I think we don't need the `beforeinstallprompt` event at all, whatever the other enhancements in webkit/Safari, looking at how Chrome(ium?) made it instant now anyway, with almost no user engagement anymore.

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).