Describing Your Progressive Web App with a Web Manifest File
Last Updated -
A web manifest file provides meta data to the browser, telling it how to theme the add to home screen experience so your brand is properly representing after you earn the deeper customer relationship. You also control how your PWA is launched form the homescreen.
Native apps have enjoyed a natural advantage over web sites because their icons are on the homescreen, after they have been installed. After an app is downloaded from the app store its icon is added to the user’s homescreen. This presence not only makes access to the app easier, it represents a deeper engagement between the customer and the business.
Don't confuse the web manifest file with the appCache manifest file. They serve two completely different purposes. The appCache describes how a web site should cache assets.
The web manifest is a JSON file containing a series of properties used to describe the progressive web app to the platform. The platform knows how to find the manifest because it is referenced in the HEAD.
… The primary properties are name, short_name and icons. These are used to compose the home screen icon and title.
{ "name": "Fast Furniture", "short_name": "Fast Furniture", "icons": […], // other properties}
Two name fields are provided so you can provide a full name and a name to be used when space is limited. This way your brand name is not truncated.
For more details on the icons, please refer to the baseline icon set article.
Before I dive into the web manifest properties I want to remind you to visit PWA Starter to generate your web manifest file and icons.
Web Manifest Properties
The remaining web manifest properties allow you to control the PWA launch process. These include theme colors, start url and display modes.
There are different display modes you can select: fullscreen, standalone, minimal-ui and browser. Fullscreen launches your application as if it were a native applications, with no browser elements.
Standalone is similar, bu the status bar may be displayed. Minimal-UI adds basic browser navigation elements. This can be useful if you have not provided navigation features to your user interface.
The browser option launches your PWA as if the user typed the address in the browser's address bar. This means it loads like a normal web page.
If you want to lock your application's orientation you can set it to either portrait or landscape. This prevents the user from rotating the experience and can be useful for video apps and games.
The theme colors are used to set the splash screen's background color and theme any browser elements that may be rendered.
The start_url defines the page loaded when the customer launches your progressive web app from their homescreen. This is very important because traditionally when a web app is added to the homescreen the current url is assigned to the homescreen icon. They are more like bookmarks and not application icons.
This means you have complete control over the start experience. Most will want to launch the site's home page, but you may define a special start page for your PWA. You can also add a queryString parameter to track homescreen activity using your server analytics.
"start_url": "/?utm_source=homescreen" There are additional properties that may add value for certain applications. For example if you still maintain a native app, you can reference it using the related_applications property.
Some services also require custom properties. For example Google Cloud Messaging requires a subscription id be added to the manifest file. Windows Store applications may also use this to control what platform features the application can use.
Triggering the Add to Homescreen on Chrome
Triggering the add to home screen experience only happens if you meet the platform's criteria. There is nothing in the web manifest specification to define these criteria. Each browser is free to enforce their own rules.
Chrome has the following rules:
- Has a web app manifest file with:
- a short_name (used on the home screen)
- a name (used in the banner)
- a 144x144 png icon
- a start_url that loads
- Has a service worker registered on your site.
- Is served over HTTPS
Since Chrome first landed support for progressive web apps, the add to home screen trigger rules have changed. These rules are destined to change in the future as well. Basically each platform is reviewing how consumers respond to the home screen prompt and adjust over time to maximize responses.
Controlling the Add to Homescreen Prompt
Maybe you don't want to rely on the browser's logic to prompt the visitor to add your site to their homescreen. Chrome supports the 'beforeinstallprompt' event. An event listener can be used to intercept the process and either stop, delay or just track the activity.
This code shows how to intercept the event and track the user's response.
window.addEventListener('beforeinstallprompt', function(event) { event.userChoice.then(function(result) { if(result.outcome == 'dismissed') { // They dismissed, send to analytics }else { // User accepted! Send to analytics } }); }); If you want to prevent the prompt, and there are many use cases for this, the following code suppresses the prompt.
window.addEventListener('beforeinstallprompt', function(e) { e.preventDefault(); return false;});There are many more logic variations you might employ. Of course it all depends on your application's needs.
Polyfil Legacy Platforms
Not all browsers support web manifests and the add to homescreen prompt, iOS and Internet Explorer are the primary culprits. This does not mean you cannot manufacture the experience. I have been prompting users to add web apps to their home screen for years using Matteo Spinelli's AddToHomescreen library.
I recently updated the library to handle all the modern add to homescreen options across all browsers. It is highly configurable so it should be able to handle most prompting scenarios appropriate for your sites and applications.
This is a great tool for prompting iPhone or iPad Safari users with JavaScript add your progressive web app's icon to their home screen.
The great thing is you can dynamically add the support code using some basic feature detection. My criteria is service worker support because browsers that support an add to homescreen experience tend to support service workers.
The following code dynamically appends the addtohomescreen CSS.
if ('serviceWorker' in navigator) { // add addToHomeScreen CSS cssLink = document.createElement("link"); cssLink.id = "addToHomeScreen"; cssLink.rel = "stylesheet"; cssLink.type = "text/css"; cssLink.href = "css/libs/addtohomescreen.css"; document.head.appendChild(cssLink); } The nice thing is you don't need this code loaded immediately because you want to prompt the user after some engagement time. So use this time to delay load the library.
The native add to homescreen experience may be the best solution, but intercepting the native prompt or adding it to legacy platforms can be better because you can drive the experience yourself.
For example, FireFox is not actively prompting users to add PWAs to the homescreen. They are rendering a subtle icon to notify the user. Microsoft Edge currently has no formal plan to prompt pinning icons or tiles. So crafting an experience can provide advantages.
Progressive Web Apps From Beginner to Expert
Do you want a much more detailed set of progressive web app and service worker tutorials? I just launched a new course,Progressive Web Apps : From Beginner to Expert.
This course covers everything you need to know to make any website a progressive web application. There are beginner topics to help anyone get started with progressive web app and service worker development. There are also modules to teach you how to polyfil many modern PWA features like offline and add to homescreen tactics.
Enroll today and save $171 off the $200 price. Progressive Web Apps : From Beginner to Expert is only $29 for a limited time.
Summary
A valid web manifest file is a core progressive web application requirement. Without this file the platform does not know enough about your PWA to create a proper launch and homescreen experience.
Do not overlook the importance of this file as it could break your progressive web application.
Not all platforms have a proper add to homescreen experience, but this does not mean you cannot add your own. The add to homescreen experience is not a standard, so support and heuristics vary by platform.