Want to work with us?Get in touch

Web App Manifests - A Guide to get your website on a user’s Home Screen


Jamie Maria Schouren

May 29, 2019

This blog contains information about how to make your website ready to be installed on a user’s Home Screen, while creating a Native App experience. It will talk about the why, what and how of the use of Web App Manifests.

The numbers about Native Apps

According to Newzoo Global Mobile Market Report 2018, there are at the moment 3.3 billion active smartphone users worldwide. When we consider that for the average person it is the primary device (and sometimes only device) for internet access, it is not hard to draw the conclusion that our websites deserve to perform well and work perfect on mobile.

To throw in some more numbers: according to other research done by Google and Comscore, mobile websites get more visitors than mobile apps, but visitors spend more time in apps. Mobile users are spending 87 percent of their time in apps, versus just 13 percent on the web.

According to eMarketer research, users spend two hours and 11 minutes per day using mobile apps, but just 26 minutes browsing the web on a mobile device.

So while we visit a lot of websites, we don’t really spend time in them. It seems we love using apps, but when it comes to downloading them we are not so keen about them anymore: the average amount of apps downloaded per user per month is zero. Yes, you read that correctly, it is zero.

And if you thought (or hoped) the numbers game was over, it’s not. Because one more important statistic to consider is why we spend so much time in our native apps:

An app provides a direct access point from the home screen of a mobile device, and a native app experience is typically slicker and faster than a comparable web experience

Cathy Boyle, eMarketer principal analyst .

In short, we spend more time in apps as they provide the ultimate user experience: fast, engaging, network independent, user-friendly etc.

So what if…. We can isolate those values, those wonderful features of Native Apps — and bring them to our websites? With so many users visiting websites — can we offer them the amazing native app features to engage them and fall in love with us?

Since a couple of years we can actually do that. We call them “Progressive Web Apps”. More details about them, you can read it all in my blog here.

If you want to try it out, please have a look at product DEITY Falcon, a framework/ toolkit to build Progressive Web Apps for any type of website, including full PWA storefronts for Magento, for WordPress, for BigCommerce and more! Built with ReactJS and NodeJS.

Add to Home Screen — How to do it

Although I would definitely and strongly recommend to turn your current front-end and native apps into a complete and single Progressive Web App, so you can not only profit from the benefits a PWA will bring you, but also can just focus on one platform instead of three (bye bye Native Apps), you can get a kick start ahead of your competition by taking the first step: giving your website to ability to be installed on the Home Screen of a user.

To enable your website /web app to be added to a Home Screen, it needs the following:

  • To be served over HTTPs — the web is increasingly being moved in a more secure direction, and many modern web technologies will work only on secure contexts.
  • To have a Web App Manifest file with the correct fields filled in, linked from the HTML head.
  • To have an appropriate icon available for displaying on the Home Screen.
  • Chrome additionally requires the app to have a service worker registered (e.g., so it can function when offline).

Image for post

Web App Manifest

The Web App Manifest

Basically a Web App Manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched, it is providing information about an application.

It provides developers with a centralised place to put metadata associated with a web application such as its name, author, icon and description but it can also include the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen).

For the more advanced users, the manifest even allows a developer to “scope” a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to “deep link” into a web application from other applications.

With the Web App Manifest in place, a website can be installed on the Home Screen of a device, which will provide users with quick access and a rich, native-app like experience.

So in short: with a Web App Manifest you can give your website the capability to be placed on the Home Screen of a user, which will then behave like a native app after installing it on the Home Screen. It is not a shortcut to your website, it will not open the browser!

“More than 50 percent of all smartphone users move mobile apps to the home screen for easy access.”


Image for post

Web App Manifests examples

A Web App Manifest does not have to be a complicated piece of code. You can start very simple by just adding basic information, like for example:

name: My Shop App,
description: This app helps you shop your favorite brand.,
icons: [
src: images/icon.png,
type: image/png,
sizes: 192×192

However, the fields needed for full “Add to Home Screen” are as follows:

  • background_color: Specifies a background color to be used in some app contexts. The most relevant one to Add to Home Screen is the splash screen displayed when the app icon on the Home Screen is tapped and it first starts to load (this currently appears only when apps have been added to the Home Screen by Chrome).
  • display: Specifies how the app should be displayed. To make it feel like a distinct app (and not just a web page), you should choose a value such as fullscreen (no UI is shown at all) or standalone (very similar, but system-level UI elements such as the status bar might be visible).
  • icons: Specifies icons for the browser to use when representing the app in different places (such as on the task switcher, or more important, the Home Screen). We’ve included only one in our demo, but there can be much more.
  • name/short_name: These fields provide an app name to be displayed when representing the app in different places. name provides the full app name, and short_name provides a shortened name to be used when there is insufficient space to display the full name. You are advised to provide both if your app’s name is particularly long.
  • start_url: Provides a path to the asset that should be loaded when the added-to-Home Screen app is launched. Note that this has to be a relative URL pointing to the site index, relative to the url of the manifest. Also, be aware that Chrome requires this before it will display the install banner, whereas Firefox doesn’t require it for showing the home-with-a-plus icon.

The more typical Web App Manifest will then look something like this:

short_name: Shop,
name: My Shop App,
description: This app helps you shop your favorite brand.,
icons: [
src: images/icon.png,
type: image/png,
sizes: 192×192
start_url: /my-shop/,
background_color: #FFFFFF,
theme_color: #FFFFFF,
display: standalone


Appropriate Icon

As shown in the above manifest listing, we are including a 192 x 192 px icon for use in our app. You can include more sizes if you want; Android will choose the most appropriate size for each different use case.

You could also decide to include different types of icons so devices can use the best one they are able to (e.g., Chrome already supports the WebP format).

Note that the typemember in each icon’s object specifies the icon’s mimetype, so the browser can quickly read what type the icon is, and then ignore it and move to a different icon if it doesn’t support it.

In terms of how to design the icon, you should follow the same best practices you’d follow for any Android icon (see the Android icon design guidelines).

Link the HTML to the manifest

To finish setting up your manifest, you need to reference it from the HTML of your application’s home page:

<link rel="manifest" href="manifest.webmanifest">

Browsers that support “Add to Homescreen” will know where to look for your manifest once this is in place.

Splash screens

In Chrome 47 and later, a splash screen is displayed for sites launched from a homescreen. This splashscreen is auto-generated from properties in the web app manifest, specifically:

  • name
  • background_color
  • The icon in the icons array that is closest to 128dpi for the device.
Related image

Installable Web Applications

What we all want eventually is to appear with our website on the user’s device Home Screen. We don’t just want to be a bookmark, a shortlink to a website, but we want to provide the user with the full ‘native app experience’.

Technically this means that “a user agent will install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest’s members applied to it. That is, the manifest’s members, or their defaults, are in effect on the top-level browsing context.

By providing the correct information on installation, the device will then distinguish an installed web application from a traditional bookmark, and give the full native app experience. This means that a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu.

When launched, the manifest is applied by the users device to the top-level browsing context prior to the start URL being loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.

Installable Prompts

There are multiple ways that the installation process can be triggered:

  • The user can manually trigger the installation process through the devices UI. This is at the moment (march 2019) the only option to install a Progressive Web App on an iOS device.
  • The installation process can be triggered through an automated install prompt: when the browser detects there are sufficient ‘installability’ signals to warrant installation of the web application, a pop-up or message can appear on the device asking the user if they want to install the Progressive Web App on their device’s Home Screen. This is at the moment only available for Android.
  • The installation process can occur through a site-triggered install prompt: the site can programmatically request that the device present an install prompt to the user. Be aware however that the device MAY restrict the availability of this feature to cases where, for instance, there are sufficient ‘installability’ signals to warrant installation of the web application.

Image for post

Install on iOS

Prior to presenting an automated install prompt, a user agent MUST run the steps to notify that an install prompt is available, to give the site the opportunity to prevent the default action (which is to install the application). Alternatively, the user agent MAY run the steps to notify that an install prompt is available at any time, giving the site the opportunity to show a site-triggered install prompt without automatically showing the prompt.

In either case, when a user agent presents an install prompt, the end-user’s choice is represented either “accepted” or “dismissed”. These values are represented in the API of this specification via the AppBannerPromptOutcome enum. The AppBannerPromptOutcome enum’s values represent the outcomes from presenting the end-user with an install prompt.

The steps to notify that an install prompt is available are given by the following algorithm:

  • Wait until the Document of the top-level browsing context is completely loaded.
  • If there is already an installation process being presented, terminate this algorithm.
  • Queue a task on the application life-cycle task source to do the following:
  1. Let event be a newly constructed BeforeInstallPromptEvent named beforeinstallprompt, with its cancelable attribute initialised to true.
  2. Let mayShowPrompt be the result of firing event at the Window object of the top-level browsing context.
  3. If mayShowPrompt is true, then the user agent MAY, in parallel, request to present an install prompt with event.

Image for post

Installation Prompt on Android

What does Add to Home Screen not give you?

As we all now know now how to add our website on a user’s device Home Screen, and give it a real native app experience (no browser shortcuts!), it is good to bear in mind that this will only make the app easily accessible — it doesn’t download the app’s assets and data to your device and make the app available offline, or anything like that.

To make your app work offline, you have to use the Service Worker API to handle storing the assets offline, and if required, Web storage or IndexedDB to store its data. And similar additional work is needed to send Push Notifications, get acces to hardware of a phone etc. In future blogs we will post more about Service Workers, and explain how to do this.

Getting started

If you are looking to give your users a first taste of a Native App Experience, you can start by adding a Web App Manifest to your website. This will allow your website to be added to the homescreen, followed by the option of using a splash screen and enhance the overall experience drastically. Later we strongly recommend to take the next steps and offer a complete full Progressive Web App.

While a few years ago this could only be done from scratch, now it is super to get started. If you are looking to build a PWA Front-end for Magento, for BigCommerce, for WordPress or any other back-end withNodeJS and ReactJS: please have a look at our product DEITY Falcon here.

Keep on reading.

Learn more about the impact of our products and how you can benefit with in depth articles, video's and talks from our experts.

More articles

The power of PWA combined with Push Notifications

Deity | Nov 16, 2020Read Article

Turn on the FIRE during the festive season

Deity | Nov 10, 2020Read Article

Winners of the BC Best User Experience Award 2020

Deity | Oct 22, 2020Read Article
Want to stay up to date?

Sign up for our newsletter and be the first to receive all the latest updates.

See our privacy policy for further information about processing of your personal data.