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

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

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

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

Author

Jamie Maria Schouren

Co-Founder

Author

Jamie Maria Schouren

Co-Founder

Author

Jamie Maria Schouren

Co-Founder

Author

Jamie Maria Schouren

Co-Founder

Category

Educational

Publish Date

May 29, 2019

An example of a typical smartphone application

The numbers about Native Apps

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

According to Newzoo Global Mobile Market Report 2018, there are currently 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 perfectly 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 on 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.

Chart of average time spent per dat with mobile internet among US adults

So, while we visit a lot of websites, we don’t really spend time on them. It seems we love using apps, but when it comes to downloading them, we are not so keen on 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 on 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 on 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?

For a couple of years, we can actually do that. We call them “Progressive Web Apps” or "PWA". For more details, read more about PWA here.

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

Add to Home Screen — How to do it

I would definitely and strongly recommend turning 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). However, you can get a kick start ahead of your competition by taking the first step: giving your website the 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).

Web App Manifests

Basically, Web App Manifests are JSON documents that contain startup parameters and application defaults for when a web application is launched. They provide information about an application.

Furthermore, Web App Manifests provide developers with a centralized place to put metadata associated with a web application, such as its name, author, icon, and description. Also, it can include the preferred URL to open when a user launches the web application. The manifest further 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 Web App Manifests, you can give your website the capability to be placed on the Home Screen of a user. This will then behave like a native app after installing it on the Home Screen. It is not a shortcut to your website as it will not open the browser!

Chart showing the percentage of users that intentionally move apps to home screen

Web App Manifests examples

Web App Manifests do not have to be complicated pieces of code. You can start very simple by just adding basic information, for example:

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

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 only appears 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. Both very similar, but with standalone, 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. For example, on the task switcher, or more importantly, the Home Screen. In our demo. we’ve included only one, but there can be many 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": "192x192" } ], "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 one that best suits them (e.g., Chrome already supports the WebP format).

Note that the typemember in each icon’s object specifies the icon’s mime-type. This way, the browser can quickly read what type the icon is, 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).

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 home screen. This splash screen 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.

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 short link 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 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. For example, appearing as a labeled icon on the home screen, launcher, or start menu.

When launched, the manifest is applied by the user's 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 device's 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 the 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 the installation of the web application.

Example of an automated install prompt

Prior to presenting an automated install prompt, a user agent MUST run the steps to notify that an install prompt is available. This gives 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 as 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 of 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:

Let the event be a newly constructed BeforeInstallPromptEvent named beforeinstallprompt, with its cancelable attribute initialized to true.

Let mayShowPrompt be the result of firing event at the Window object of the top-level browsing context.

If mayShowPrompt is true, then the user agent MAY, in parallel, request to present an install prompt with the event.

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 nor 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. Similar additional work is needed to send Push Notifications and get access to the hardware of a phone, etc. In future blogs, we will post more about Service Workers and explain how to do this.

Getting started with Web App Manifests

If you are looking to give your users the 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 home screen, 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, BigCommerce, WordPress, or any other Back-End with NodeJS and ReactJS, please have a look at our product Deity PWA Storefront.

Jamie Maria Schouren

Jamie is addicted to ecommerce, in love with code and her mind bound to business. Driven by the urge for innovation, she co-founded Deity, with which she is on a mission to spark an online revolution to evolve web technologies.

Jamie Maria Schouren

Jamie is addicted to ecommerce, in love with code and her mind bound to business. Driven by the urge for innovation, she co-founded Deity, with which she is on a mission to spark an online revolution to evolve web technologies.

Jamie Maria Schouren

Jamie is addicted to ecommerce, in love with code and her mind bound to business. Driven by the urge for innovation, she co-founded Deity, with which she is on a mission to spark an online revolution to evolve web technologies.

Jamie Maria Schouren

Jamie is addicted to ecommerce, in love with code and her mind bound to business. Driven by the urge for innovation, she co-founded Deity, with which she is on a mission to spark an online revolution to evolve web technologies.

Trusted by

Find out how you can

supercharge your business.

Find out how you can

supercharge your business.

Find out how you can

supercharge your business.