How to Use the 'beforeinstallprompt' 🔔 Event to Create a Custom PWA Add to Homescreen Experience 👍
Last Updated -
Business owners want a clean, native way to nudge users to install their Progressive Web App.
Edge, Chrome and Samsung Internet offer a native installation prompt. This is done by adding an event handler to the beforeInstallPrompt event.
Other browsers, including iPhone Safari, still require a manual prompt. Users can still install or add a PWA to the homescreen through existing channels.
There are still many variances with the overall PWA engagement process between browsers and platforms. That is why I created the Add to Homescreen Library. It helps level these differences so you can provide the best prompt for the browser and platform.
The Chromium based browsers trigger the beforeinstallprompt event in the background. You must register an event callback to handle the event triggering.
In fact, the prompt is gated behind a user action. This is a technical way of saying the user must click a button before you can display the native installation prompt. I will give you a simple example later in this post.
In the past Mateo Spinnelli's AddToHomeScreen library worked for both iOS and Android web apps in the pre-PWA days. I used this library as the base for my new Add To Homescreen library.
It doesn't solve the completely problem because other browsers still don't have an automated prompt and install experience, just a manual process.
This means you will still need to solve the cross-browser, cross-platform problem.
In this post I will give you a high level example of how you can build an add to homescreen prompt experience for your progressive web apps.
In the meantime, if you want a nice tool to start your PWA journey, visit PWA Starter. You can walk through the wizard and it will generate a full set of icons, include the Chrome add to homescreen icon as well as Windows start menu and iOS homescreen icons. You will also have a valid web manifest file and basic service worker.
The New Add To Homescreen Flow
If the add to homescreen criteria are met the beforeinstallprompt event is triggered.
The criteria include the following:
- The web app is not already installed
- Meets a user engagement heuristic (currently, the user has interacted with the domain for at least 30 seconds)
- Meets the Progressive Web App criteria:
- Includes a web app manifest that includes:
- short_name or name
- icons including a 192px and a 512px version
- start_url
- Served over HTTPS (required for service workers)
- Has registered a service worker with a fetch event handler
- Includes a web app manifest that includes:
I want to note the fetch event handler cannot be a noop method, meaning it is just a placeholder. I shared last summer you just need a function, but that criteria is changing as the Chrome team evolves their feature detection.
Most of the criteria should be expected if you are familiar with progressive web apps.
The second requirement of 30 seconds of user engagement is a relative requirement. And this demonstrates how the add to homescreen prompt is a non-standard feature.
The 30 second time frame I suspect is arbitrary. And what qualifies as interacting with the domain is also subjective. I have not seen qualitative criteria as to what triggers this as a positive state yet.
The key for you to remember is capturing the beforeinstallprompt event and controlling the process.
- Listen for the beforeinstallprompt event
- Notify the user your app can be installed with a button or other element that will generate a user gesture event.
- Show the prompt by calling prompt() on the saved beforeinstallprompt event.
The following code should be added to your site's JavaScript. For this demonstration I upgraded the 2048 game I announced a few months ago.
var deferredPrompt; window.addEventListener('beforeinstallprompt', function (e) { deferredPrompt = e; showAddToHomeScreen(); }); The first thing you should do is create a variable outside the scope of the beforeinstallprompt event handler. This way you can reference it later. This handler saves a reference to the beforeinstallprompt event object. You can use this later to trigger the add to homescreen prompt on demand.
The next step is to call the showAddToHomeScreen method. This simply shows a message to the user about the application being elible to install.
function showAddToHomeScreen() { var a2hsBtn = document.querySelector(".ad2hs-prompt"); a2hsBtn.style.display = "block"; a2hsBtn.addEventListener("click", addToHomeScreen); } This just changes the notifications display state from none to block. Again this is an overly simple solution. For a real production application I would employ much better UX ;)
What you should take away from this step is how you are responsible for notifying your customer they can add your PWA to their homescreen, or in the case of Windows 'install' the application.
If you have been paying attention to recommended prompting practices you should not brute force actions like asking for push notification, geo-location or other permission based actions. Add to homescreen is similar.
This approach makes the task less intrusive, which means you are more likely to get the engagement numbers you are after.
I made the message element live by binding a click event handler. When clicked or tapped, the addToHomeScreen method is triggered.
function addToHomeScreen() { var a2hsBtn = document.querySelector(".ad2hs-prompt"); // hide our user interface that shows our A2HS button a2hsBtn.style.display = 'none'; // Show the prompt deferredPrompt.prompt(); // Wait for the user to respond to the prompt deferredPrompt.userChoice .then(function(choiceResult){ if (choiceResult.outcome === 'accepted') { console.log('User accepted the A2HS prompt'); } else { console.log('User dismissed the A2HS prompt'); } deferredPrompt = null; }); } This will trigger the native Chrome add to homescreen banner. But first I hide the message because the user has responded to the message.
Next, I use the reference to the deferredPrompt to trigger the native prompt by calling the prompt method. The prompt method can only be called once, so don't think you can just keep bothering the visitor to add to their homescreen. Be nice!
When they respond to the prompt they can either install the PWA or chose not to. The deferredPrompt.userChoice returns a promise when this happens. It supplies a variable you can check the outcome property.
If the outcome was "accepted" you know they added or installed the PWA. Otherwise they chose not to. You can log this information to your analytics to determine what your response rates are, etc. Use those values to determine if you need to improve your user experience or not.
beforeinstallprompt Is Not a Web Standard
Unlike service workers and the web manifest file the add to homescreen prompt is not a web standard. This means browsers are and always have been able to dictate how and if the user is prompted to add a progressive web app to the homescreen.
Most browsers have implemented subtle queues to the visitor, like an icon in the address bar. Others make it discoverable in the browser's menus.
Microsoft has not yet implemented an add to homescreen process of any sort. Instead they have invested their resources in ingesting PWAs in their App Store.
At last week's Build they started hinting at a possible UI icon to alert users a PWA can be added to the desktop.
Summary
If you have a progressive web app or are planning on upgrading to a PWA soon you need to be aware of this new workflow. Use the example code I provided here to get started. Remember this is just a simple example and I encourage you to get creative with your implementations.
Unfortunately this is a Chrome only feature, but you can utilize it as a potential model to reach users in other browsers. This process should be part of your application's onboarding experience.
Remember you don't need to worry about most of the complex logic because my Add to Homescreen Library handles that for you. It won't solve every scenario but will give you a common base to build your prompts. And trust me everyone has some sort of custom rules they want to implement their prompts.
The source code is available on GitHub and play the game at 2048.love2dev.com.
