The Progressive Web Application Add to Homescreen Library Abstracts Browser and Platform Differences Away
Last Updated -
Business owners and online marketers tend to measure their Progressive Web App success by homescreen adoption. I don't blame them, it is a clear sign the consumer wants a deeper relationship with the brand.
The problem is know when and how to prompt visitors to install or add your progressive web app to their home screens.
Microsoft Edge, Google Chrome and Samsung Internet have a native event, 'beforeinstallprompt' that triggers if the site meets a minimum set of PWA requirements. The event includes a prompt object, but it can only be used in response to a user action, ie click.
Apple's iOS has always had the ability to add any website with a handful of Apple META tags to the homescreen. Today iOS Safari utilizes the web manifest file, but no native prompt event.
FireFox only offers an Add to Homescreen feature on Android. Opera and other browsers still seem to not have any notion of installation or adding that coveted icon to the homescreen.
This leaves developers in a precarious position. How do you know when and how your progressive web app can be added to the homescreen?
The good news is I created a library and tool to help you craft an add to homescreen experience that should help you earn a spot on your visitor's homescreen.
To be fair I did not create the library from scratch, but I forked Matteo Spinnelli's old Add to Homescreen library. I used this library for years to prompt on iOS. Since then Progressive Web Apps have happened and it seems Matteo has moved on from software development.
Since something needed to be done I decided to start with his library and upgrade it. Last year I released the first version of my upgrade. It included logic to determine what browser and operating system were in use and then would handle displaying an appropriate prompt.
The problem with this approach, one I inherited from Matteo's library, is tight coupling with the user interface and experience to the detection logic. The newest version removes all UI or actual prompting. Now it focuses on detecting if and how a PWA can be installed.
The main goal is to abstract as much of the platform differences away to give you a consistent way to manage the experience.
Clients have asked me to control prompting users to install the PWA using a variety of rules. The library has been designed to allow flexibility when it comes to applying your ruleset.
Over the past year I as well as my clients wanted to control the on screen visual prompts. This includes pop over banners, inline call to actions and additional menu options to trigger the action. Now all the actual visual queues are up too you to control. The library just indicates if the PWA can be add to the homescreen and what platform is being used.
It does this through a callback or hook function, onCanInstall. The library supplies an object properties you can use to drive your onscreen experience.
While having a user add your PWA to their homescreen or desktop is an important metric to measure your site's engagement success it is not the only metric.
But let's focus on it anyway!
What is Add to Homescreen?
If you follow modern best practices and leverage minimum PWA requirements your application offers the user experience benefits, even if the customer has not added the site to their homescreen or desktop.
With that being said, I am like everyone else, I want that icon on my visitor's home screens.
On Android, PWAs installed from Chrome are magically converted to a WebAPK. This is a technical term for saying the PWA is transparently packaged as a native Android app with out being a full blown app. You get app shelf and other benefits as well as the coveted homescreen icon presence.
On Windows, its not a homescreen per se, you get a spot in the start menu as well as a desktop icon. The installed instance of the PWA can also be uninstalled using the Windows uninstall process, just like any other application.
So how can you earn that coveted placement on the user's device?
There is no single answer to that puzzle. There are technical requirements, which are controlled by individual browsers. These we can handle, with some finesse.
Of course, the more difficult part is coaxing the visitor to install the progressive web app. That is where your app needs to be compelling, providing enough value for them to justify adding the site to their homescreen.
Unfortunately the Add to Homescreen library won't help with building the trust with the customer, that is still up to you.
Back to the technical. Browser and platform vendors have not made it very simple to manage. The install process is still a bit wild.
While there is an official specification for the web manifest, it leaves it open to browsers as to how they will handle the add to homescreen experience.
While the spec details how a native prompt can be managed via client-side JavaScript by wiring an event handler to the beforeinstallprompt event.
The actual user prompt flow and prompting is left open ended.
Today, Chrome, Edge and Samsung Internet are the only browsers implementing the beforeinstallprompt event.
Safari has implement some support for the web manifest, but mostly for determining what icons nd images to use for the homescreen and splash pages.
Other browsers just display a little icon in the browser's omnibox to indicate the site can be installed, if anything at all.
It is these variations in how a user is prompted by the browser and the actual process to install a PWA that lead to frustration. And don't think Microsoft and Google have things figured out, they don't.
It’s frustrating with Chrome because it seems they are continually tinkering with the experience. A couple of years you could just bind to the beforeinstallprompt event and prompt the user. That has changed and now the user must initiate the prompt, like from a click event, and then you can trigger the actual prompt.
As you can see the variations are all over the place. So, it is left up to you, the site owner, developer and designer to create a consistent add to homescreen prompt experience.
It is these variations that prompted me to design this library to abstract the differences away as much as possible.
Now to review how to the library works, how to use it on your site.
How the Add to Homescreen Manager Works
Before I do that, you can always use our PWA Starter to walk you through the process of configuring the library to make it easy to inject on your website as well as other PWA support files.
First, let's look at how different browsers implement the add to homescreen experience.
Chrome and Edge
The Chromium project has the best progressive web application homescreen prompt mechanism, the beforeinstallprompt event and a native prompt banner. I keep hoping other browsers will ship support for this native event, but for now it is limited.
I love there is a native prompt, the problem is it seems Google keeps changing the user experience around the install prompt. The main thing to remember is the beforeinstallprompt event will trigger if the browser determines the site meets its minimal PWA requirements.
Of course each browser determines its own criteria of what exactly are the minimum PWA and PWA installability requirements.
The way the prompt is supposed to work is you capture the event and keep it from triggering until you want it to prompt the user.
var _beforeInstallPrompt;
if ( "onbeforeinstallprompt" in window ) {
window.addEventListener( "beforeinstallprompt", beforeInstallPrompt );
}
function beforeInstallPrompt( evt ) {
evt.preventDefault(); _beforeInstallPrompt = evt;
}
In this code example a feature detection is made to see if the beforeinstallprompt event is supported. If it is then an event handler is created on the window object.
If the site meets the minimum criteria the event will trigger according to the browser prompting heuristics.
Beware, just because the event fires does not mean the prompt will trigger. The published rule requires the prompt to be displayed in response to a user action. This means the user should click a button or some other action.
Because the Add to Homescreen library controls the display on an initial banner prompt or possibly other page elements, like a menu option etc, you are covered for the user gesture requirement.
Prompting the User Natively
After you have captured the native prompt, you need to trigger that actual user prompt. To do this you must call the 'prompt' method on the event object you captured. It returns a promise and resolves a value to let you know what the user chose.
return _beforeInstallPrompt.prompt()
.then( function ( evt ) {
// Wait for the user to respond to the prompt
return _beforeInstallPrompt.userChoice; } )
.then( function ( choiceResult ) { //do stuff here
} )
.catch( function ( err ) { if ( err.message.indexOf( "user gesture" ) > -1 ) {
//recycle, but make sure there is a user gesture involved
} else if ( err.message.indexOf( "The app is already installed" ) > -1 ) {
//the app is installed, no need to prompt, but you may need to log or update state values
} else {
return err;
}
});
The prompt method does not always resolve, it may throw an exception, which you need to catch.
In the example above I capture the two most common errors, user gesture required or the app is already installed. Exceptions are thrown because the ability to display the native prompt failed.
If this sounds confusing, don't worry, the Add to Homescreen library abstracts all this away so you don't need to worry about handling all the plumbing.
If the browser supports beforeinstallprompt when the user choses to install the application from the A2HS prompt the native prompt will be displayed.
And don't worry, we have you covered for other browsers too, like iOS.
How You Can Add a Progressive Web App to your iPhone or iPad Homescreen
Apple of course was the first to the modern mobile world. When they released the iPhone the original app strategy was HTML5 apps you added to the homescreen.
Since then Apple has supported this add to homescreen installation flow with touch icons and the ability to open installed web apps full screen.
The real issue with the experience is they never added any native prompting experience. Instead the user has to walk through a collection of steps to install the application.
- Open up Safari and load a web site.
- At the bottom of the screen is the share icon [insert icon here]. It is an arrow pointing up from a square.
- At this point the share sheet is rendering. You will need to slide the icons to the left to reveal the 'Add to Homescreen' button.
- You'll be asked to choose a name for the homescreen icon. So, you know, pick a good one and save it. When you're done it'll show up on your homescreen and you'll never have to type in that stupid URL ever again.
Even though there is no native prompt available on iOS you can still use the existing 'plumbing'. The Add to Homescreen library will still trigger a prompt just like the beforeinstallprompt experience.
Instead of displaying the native prompt, which of course is not available, a set of screenshots will animate to help educate the user on how to add the site to their homescreen.
The user will still need to walk through the process, unfortunately there is no way to programmatically install the site to their homescreen.
Safari is the only iOS browser. So other browsers don't come into play, but again the library abstracts you away from the difference.
You can customize the images and steps that are displayed to guide the user through the process.
FireFox, Opera, Samsung and other browsers
Last, the other browsers. Other than Chrome and the new Edge most browsers don't really support an add to desktop on laptops, so the add to homescreen experience in other browsers is largely limited to Android.
Right now, these browsers don't support the beforeinstallprompt, so the experience is sort of like iOS, manual.
So I borrowed from the iOS prompting experience. The library detects the different platforms/browsers and will trigger an image or sequence of images to guide the user to the menu item or omnibox trigger to add the PWA to the homescreen.
Configuring Your Rules
Confused?
Don't worry, most who try to tackle this topic are as well.
This is why the Add To Homescreen library is helpful. It does a sequence of feature, browser and platform detections to determine if a PWA can be installed or added to the homescreen.
if ( window.addToHomescreen ) {
ath = addToHomescreen( {
onCanInstall: function ( platform, _instance ) {
//run any on screen prompting logic from here
},
onBeforeInstallPrompt: function ( platform ) {
//this triggers in response to the browser triggering the beforeInstallPrompt event
console.log( "native prompt: ", platform );
}
} );
}The previous version of this library had a cadre of configuration options because it included logic to determine if the page load qualified to display an on screen prompt. All of that has been removed. It is up to you to determine if and how you display a call to action.
Both callbacks, onCanInstall and onBeforeInstallPrompt, pass a 'platform' object. This object contains a set of properties you can use to drive your visual queues. For example if it is an iPhone you can display an image showing how to tab the share button and swipe to the right to access the add to homescreen button.
Something a few of my clients have opted to do is use the platform object to direct users to platform specific landing pages to sell the installation benefits and how the user can install from their browser platform.
Now that you have customized the prompting logic you will need to customize the actual prompt.
Summary
The goal is to control how you prompt and tease your visitors to add your progressive web app to their homescreen. Instead of putting this responsibility on you or your developer's shoulders the Add to Homescreen library provides a controlled mechanism to abstract away platform differences.
While each browser seems to require a different process for users to add Progressive Web Apps to their homescreen or desktop you should not be intimidated by this. Instead you can use this library to give you a more common interface to handle these scenarios.
Hopefully this library can be reduced if all browsers would support the beforeinstallprompt event. You will still need to control when the prompt is displayed of course. So the PWA Add to Homescreen library will always have its place in everyone's Progressive Web App journey.