How to show PWA install banner (Add to Homescreen) for your website

4 min readApr 26, 2020

Progressive web apps — Progressive Web Application

Recently, my organisation decided to prompt the user for adding the website on the home screen which will allow them to access the user base which is more interested in their content. This has many implications such as we can customize content for those users, offer a better user experience, subsequently providing offline experience, etc.

Here is the reference code: https://github.com/amitsingh-007/react-pwa-boilerplate.
This code is deployed at https://react-pwa-boilerplate.vercel.app/ so that you can install it on msite and desktop and try it yourself.

So this started by configuring a service worker for your web application. Setting up a service worker for your web application is quite simple and straightforward. The best guide to set up and understand the service worker is Google’s Documentation. Assuming that the service worker is set up and working as desired, we can now head for the PWA prompt.

The Manifest File

You might have heard of the manifest file at some point in development or during auditing other web applications. A manifest.json, commonly named as manifest.webmanifest.json, is a .json file which tells the browser how the PWA will be installed and its behaviour after install. It is typically served from the root directory of the project. A typical manifest file looks like this:

manifest.json

You can read in detail about each key in the manifest.json file on web.dev. For further details and in-depth features, refer MDN web docs.

Some important things to note are:

You need at least 192X192 and 512x512 size images to prompt Add to homesceen for the user on Google Chrome.
Add to homescreen(A2HS) will never be prompted in incognito/private window.
Since one of the basic requirements of service worker is that none of your requests on your page should serve over HTTP, so if your page is served over HTTP, then it will never prompt for A2HS.
Since my request goes through Microsoft IIS, I had to allow .json file to serve over HTTPS and not get blocked:

# Ignore json, js and css file
RewriteRule ^/(.*)(\.json|\.js|\.css)

Adding reference for the manifest file

Now that you have added the manifest.json file in the root directory of your project, the next step is to add a reference to it so that browser can know if a manifest.json file exists for your web app. There are two ways to do this:

Add it in the <head> of your common layout so that every page gets it.
Since we have our web app in React, we added it in Helmet on client code:

Add a reference to manifest.json file

Note: We also addded theme-color meta tag because it allows you to give custom color on toolbar of browsers which supports it.

theme-color meta tag — **theme-color** meta-tag example

Check eligibility for PWA install prompt

Under the Applications tab in Chrome Dev Tools, you can see a manifest option. Select it and you can see what’s wrong with your manifest file and if it is perfectly fine, it will show no error/warning. One can also validate their manifest here.

You can also go one step further to ensure your web app is eligible for PWA prompt by auditing your web app. Under the Audit tab in Chrome Dev Tools, you can audit your web app in the lighthouse. After the audit is complete, you can check under PWA section, if Installable is green or not.

PWA lighthouse audit, Installable — Lighthouse audit

Configuring Service Worker

If you have configured service worker with install and activate event but didn’t have fetch event listener, this will not work because the service worker needs the fetch event of manifest.json file in order for this to work.

Bare minimum fetch listener in sw.js

User actions tracking

Last but not least is the ability to track the effectiveness of the PWA install banner on your web app. There are many events that fire on PWA prompt and successive user actions. I have shared what is essentially needed to determine if we have any impact on users interest in our web app.

So these are pretty much the only necessary steps that one needs to follow in order to show Add to Homescreen to the user.

Add to homescreen, pwa install banner prompt — PWA install banner prompt (Add to home screen)

I have provided more useful links for further PWA install experience:

https://web.dev/customize-install/
https://web.dev/promote-install/

For any further queries or questions, comment down below or reach out to me on my mail: amitsingh5198@gmail.com