Progressive Web Apps install banner

In a previous post I talked a little about creating installable web apps. One important thing that I didn’t cover is how to automatically prompt a user on your web app to add it to their home screen.

Serve over https

One of the requirements for chrome to show an app install banner is that the app is served over HTTPS. This can be done in a few ways depending on your server. I wrote a post on how to get free SSL certificates using Let’s encrypt that should help you get started.

manifest.json

In my installable web apps article I showed a sample manifest.json file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "name": "Awesome App",
  "start_url": ".",
  "display": "standalone"
  "icons": [
    {
      "src": "icons/launcher-2x.png",
      "sizes": "96x96"
    },
    {
      "src": "icons/launcher-3x.png",
      "sizes": "144x144"
    },
    {
      "src": "icons/launcher-4x.png",
      "sizes": "192x192"
    }
  ]
}

For the install banner to be shown, there are 5 things your manifest.json file must contain:

• name
• short_name
• start_url
• display (It must be standalone or fullscreen)
• At least a 144×144 icon

In the example above I’m missing short_name, so let’s add it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "Awesome App",
  "short_name": "Awesome App",
  "start_url": ".",
  "display": "standalone"
  "icons": [
    {
      "src": "icons/launcher-2x.png",
      "sizes": "96x96"
    },
    {
      "src": "icons/launcher-3x.png",
      "sizes": "144x144"
    },
    {
      "src": "icons/launcher-4x.png",
      "sizes": "192x192"
    }
  ]
}

Service worker

A service worker is piece of JavaScript that the browser will load and run in the background of your application. Having a service worker is a requirement for showing an app install banner. To register a minimal service worker you can add this script on your main page:

1
2
3
4
5
if ('serviceWorker' in navigator) {
  window.addEventListener('load', function() {
    navigator.serviceWorker.register('/sw.js');
  });
}

This code registers a service worker located in /sw.js. We need to create that file and add a fetch event listener:

1
self.addEventListener('fetch', function() { });

You can add more stuff if necessary, but this is the minimum requirement.

Testing

Once you have completed these requirements your app will be ready for showing the install banner to your users. The banner will be shown automatically to users that after using your web app, return and use it again 5 minutes (or more) later.

If you tried this and it didn’t work you can also trigger this manually from Chrome developer tools for desktop. Open the Application menu on the developer tools. On the left panel select Manifest under Application. Click the Add to homescreen button on the right panel. For verifying on your mobile device you can follow the same steps using remote debugging.

If everything went well you will see a banner on the top of the screen suggesting you to add this App to your desktop. If you get an error, review the steps above.