Add to Home Screen

Pete is a Developer Advocate

If your PWA has use cases where it’s helpful for a user to install your app, for example if you have users who use your app more than once a week, you should be promoting the installation of your PWA within the web UI of your app.

Add to Home Screen, sometimes referred to as the web app install prompt, makes it easy for users to install your Progressive Web App on their mobile or desktop device. After the user accepts the prompt, your PWA will be added to their launcher, and it will run like any other installed app.

Chrome handles most of the heavy lifting for you:

On mobile, Chrome will generate a WebAPK, creating an even more integrated experience for your users.
On desktop, your app will installed, and run in an app window.

What are the criteria?

In order for a user to be able to install your Progressive Web App, it needs to meet the following criteria:

The web app is not already installed.
- and prefer_related_applications is not true.
Meets a user engagement heuristic (currently, the user has interacted with the domain for at least 30 seconds)
Includes a web app manifest that includes:
- short_name or name
- icons must include a 192px and a 512px sized icons
- start_url
- display must be one of: fullscreen, standalone, or minimal-ui
Served over HTTPS (required for service workers)
Has registered a service worker with a fetch event handler

When these criteria are met, will fire a beforeinstallprompt event that you can use to prompt the user to install your Progressive Web App, and may show a mini-info bar. See Listen for beforeinstallprompt.

Other browsers have different criteria for installation, or to trigger the beforeinstallprompt event. Check their respective sites for full details: Edge, Firefox, Opera, Samsung Internet, and UC Browser.

Show the Add to Home Screen dialog

In order to show the Add to Home Screen dialog, you need to:

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.

Listen for `beforeinstallprompt`

If the add to home screen criteria are met, Chrome will fire a beforeinstallprompt event, that you can use to indicate your app can be 'installed', and then prompt the user to install it.

When the beforeinstallprompt event has fired, save a reference to the event, and update your user interface to indicate that the user can add your app to their home screen.

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
});

Notify the user your app can be installed

There are many different patterns that you can use to notify the user your app can be installed and promote the installation, for example, a button in the header, an item in the navigation menu, or an item in your content feed.

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen
  btnAdd.style.display = 'block';
});

You may want to wait before showing the prompt to the user, so you don't distract them from what they're doing. For example, if the user is in a check-out flow, or creating their account, let them complete that before interrupting them with the prompt.

Show the prompt

To show the add to home screen prompt, call prompt() on the saved event from within a user gesture. It will show a modal dialog, asking the user to to add your app to their home screen.

Then, listen for the promise returned by the userChoice property. The promise returns an object with an outcome property after the prompt has shown and the user has responded to it.

btnAdd.addEventListener('click', (e) => {
  // hide our user interface that shows our A2HS button
  btnAdd.style.display = 'none';
  // Show the prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  deferredPrompt.userChoice
    .then((choiceResult) => {
      if (choiceResult.outcome === 'accepted') {
        console.log('User accepted the A2HS prompt');
      } else {
        console.log('User dismissed the A2HS prompt');
      }
      deferredPrompt = null;
    });
});

You can only call prompt() on the deferred event once. If the user dismisses it, you'll need to wait until the beforeinstallprompt event is fired on the next page navigation.

The mini-info bar

The mini-infobar is an interim experience for Chrome on Android as we work towards creating a consistent experience across all platforms that includes an install button into the omnibox.

The mini-infobar is a Chrome UI component and is not controllable by the site, but can be easily dismissed by the user. Once dismissed by the user, it will not appear again until a sufficient amount of time has passed (currently 3 months). The mini-infobar will appear when the site meets the criteria, regardless of whether you preventDefault() on the beforeinstallprompt event or not.

Feedback

Was this page helpful?

Yes

What was the best thing about this page?

It helped me complete my goal(s)