![]()
One advantage native apps have enjoyed over web apps has been native home screen presence. When an app is installed, an icon is added to the user’s home screen. Users have been able to do this since the iPhone was released, but the process is manual, and largely unknown.
![]()
Matteo Spinelli created a popular library called ‘
Add to Home Screen’ many years ago to automatically prompt visitors to add a site to their home screen. The experience it creates seems to be a model for Chrome and other platforms to surface the progressive web application home screen prompt.
![]()
I have employed this library on many sites over the years with modest success. Progressive web application add to home screen prompts are more automatic. Matteo’s library only prompts the user and starts them down the manual process. But there are still a few extra, not intuitive steps users must complete. The new, native, implementations make this trimmer and more natural for the end user.
The add to home screen experience does not have a common web standard per se, but is tied to the web manifest specification. The specification leaves the actual rules and experience open-ended for each user agent to decide how they will deliver the add to home screen experience.
The Web Manifest Specification
The
Web Manifest is a JSON document, containing a series of properties (meta data) used to describe the application to the browser. The browser uses this information to drive the add to home screen and launch experiences.
Manifest properties include name, short_name, description, icons, orientation, colors and default page. Browsers are adding more feature support as we gain experience into what works well. For example, service workers have a concept of scope, which limits the URLs a service worker can control. Chrome recently added support for the manifest scope property.
The scope property defines the web application’s context or range of URLs considered to be part of the progressive web application. As long as the user navigates within the scope the browser will render PWA according to the manifest’s display property. Any navigation outside of the scope results in the page being rendered with the full browser chrome, or within the context of its progressive web application definition.
The manifest specification takes time to define skeleton rules and minimal requirements for the add to home screen experience. Rather that limited all browsers to the same rules, the specification defines instalability signals that can be used as part of the add to home screen prompt algorithm.
The prompt sequence should honor a modicum of privacy considerations and wait for the document to be fully loaded before issuing a prompt. The process should also allow the user to inspect the application name, icon, start url, origin and other properties. It is also recommended the end user be allowed to modify some of the values. For example, changing the application name on their home screen.
Referencing the Web Manifest File
The web manifest file must be referenced in the document’s HEAD.
- <head>
- ….
- <link rel="manifest" href="manifest.json">
- </head>
Optionally Manifests should be served using the application/manifest+json MIME type. This is an important setting because it is often overlooked. You should research how to define or add MIME types in your web server of choice.
Many servers block requests to files based on their type by default. This often leads to manifest files returning 404 or 403 type status codes. I see similar issues raised when PDF documents need to be served. You may need to coordinate with your network administrators or devops team to make sure your servers are properly configured.
Important note: DO NOT Cache the web manifest file using your service worker. You may not be able to update the file without updating your service worker. They should remain decoupled.
Web Manifest Properties
Owning your application’s appearance is vital to ensuring the best user experience. Every application has unique use cases, eliminating a one size fits all for progressive web applications. While most applications will want to copy native application full screen experiences, some will want to maintain a visible address bar. A standardized manifest file provides brand owners a communication channel with the browser to deliver the best, branded experience.
There are two name properties; name and short_name. The short_name is used for the icon and other places where the name display is a constrained space. Where space allows the name property is used.
- {
- "name": "Spartan Obstacles",
- "short_name": "Spartan",
- "description": "[provide your description here]",
- "start_url": “/”,
- …
- }
The start_url defines the initial url loaded when the home screen icon is selected. This eliminates the scenario where the user adds the PWA to the home screen from a deep link, like a news article. In the past the icon would be a bookmark to that article, not the home page.
The start_url can be any url within the application’s scope. It does not need to be the public home page, it can be a special PWA home page. You can also use QueryString values to drive additional tracking and dynamic behavior from the server.
The icons property is an array of ‘icon’ objects defining the url to an icon, the MIME type and dimensions.
- "icons": [
- {
- "src": "meta/spartanobstacles-logo-70x70.png",
- "sizes": "70x70",
- "type": "image/png"
- },
- …
- {
- "src": "meta/ spartanobstacles-logo-600x310.png",
- "sizes": "600x310",
- "type": "image/png"
- }
- ],
While different image types are supported I recommend using PNG as Chrome is looking for at least one PNG of 144x144 dimensions. You should include at least 4 icons, one being at least 144x144, but 192x192 is better.
My rule of thumb is to include a dozen or more icon variations to account for differences in potential platform requirements and opportunities. Windows Live Tiles can be 600 pixels wide and scale down to less than 70 pixels wide.
It is also a good idea to use some art direction when creating icons. Some logos do not work well in smaller situations. If you add your icon to the home screen and find it difficult to locate, chances are your customers will too.
![]()
A splash screen image is drawn from the icons array. Chrome chooses the image that is closest to 128dp for the device. The title is simply pulled from the name member. Specify background color using the appropriately named background_color property.
Reference your PWAs icons as URLs using an array. Each item in the array is an object that describes the icon. Include the src URL, the sizes property and MIME type. I recommend using PNG files since Chrome currently requires this format.
Controlling the Launch Style
The manifest has properties used by the platform to know how to launch the application. The display property allows you to control how the browser chrome is rendered. The default is ‘browser’, which launches the PWA in a browser, with the browser chrome.
The ‘minimal-ui’ option launches the PWA as an application, but with a minimal set of navigation UI.
‘standalone’ launches the PWA as a full screen application. The application takes most of the screen, but the some browser elements, like the status bar may be rendered.
‘fullscreen’ mode launches the application in full screen, application mode, without any browser chrome elements. To the end user there would be no difference from opening a native app.
The orientation property defines what ‘angle’ the application renders. The primary choices are landscape and portrait. The values should be self-explanatory.
The theme_color and background_color are used to represent the app and provide the default background color. The difference between these two colors are in how they are applied.
The background color refers the BODY elements default background color. This is typically set in the site’s CSS, if not it defaults back to the browser’s default. Today the de-facto background color is white, but in the early days it was grey.
The theme_color defines what color the operating system uses to visualize the application. This includes the task switching experience. Each platform offers different user experiences related to how apps are presents, so application of the theme color will vary.
Validating Web Manifest Files
The web manifest is a simple JSON document. But it’s easy to make typos or forget things. If your site is not properly registering its manifest file you will need to troubleshoot the issue. Fortunately, there are a few resources to help you validate your file.
The online
Web Manifest Validator offers a simple online check. You can either enter a URL to your manifest, upload the file or paste the code into the form.
This is not the only tool. There are a few node modules available as well as Lighthouse. I will cover Lighthouse and other tools in an upcoming article.
Tracking Home Screen Installs
Once the home screen install prompt displays the user can chose to add the PWA to their home screen, or ignore the prompt. Businesses should track and measure everything possible to make better decisions. Knowing how many home screen installs and what rate customers install their PWA provides insights into their marketing and technology investments.
Chrome supports the beforeinstallprompt event, which can be used to track this activity. You can add a handler to this event and log each user’s choice.
- 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
- }
- });
- });
You can POST the user’s choice to your analytics system. This could be a custom API to your internal analytics or even tied to your third-party service, like Google Analytics.
The beforeinstallprompt is part of the web manifest specification, but at this time is only supported by Chrome. Hopefully other browsers will add support soon.
Browsers that don’t support beforeinstallprompt can also provide feedback. The web manifest’s start_url can be set either to a special start URL, or a custom querystring value appended to the default URL. You will need to add logic to your log analyzer to track this behavior. Besides just knowing how many home screen installs you have, you can also track how many times users launch your PWA as opposed to those who have not installed your PWA.
Disabling the Home Screen Prompt
The beforeinstallprompt can also be used to suppress the Chrome automatic prompt. This time, like breaking the default form submission, call the preventDefault function and return false.
- window.addEventListener('beforeinstallprompt', function(e) {
- e.preventDefault();
- return false;
- });
This will block the behavior in Chrome. Right now I don’t know how to suppress the prompt on other platforms as they do not support the beforeinstallprompt event, yet.
The Add to Home Screen Experience
The emergence of an automatic prompt to a visitor to add your progressive web app to their home screen is exciting. But what are the rules to determine how this experience triggers and what the customer will experience? Here is where each browser can choose a different path. Some of the requirements are defined in the web manifest specification, but the experience is left open ended for browsers to implement as they see fit.
Right now, Chrome has the most sophisticated experience. They have established the following criteria to automatically trigger the add to home screen experience,
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 (the icon declarations must include a mime type of image/png)
- a start_url that loads
Has a service worker registered on your site.
- Has a fetch event handler
Is served over HTTPS (a requirement for using service worker).
Is visited at least twice, with at least five minutes between visits.
FireFox, Samsung and Opera have similar requirements. FireFox will trigger the experience on Android, but not the desktop. You can allow the experience on desktop, but it is hidden behind a flag.
The Chrome Add to Home Screen Experience
Chrome first looks for icons that match the density of the display and are sized to 48dp screen density. If none are found, it searches for the icon that most closely matches the device characteristics. If, for whatever reason, you want be specific about targeting an icon at a particular pixel density, you can use the optional density member, which takes a number. When you don’t declare density, it defaults to 1.0. This means: “use this icon for screen densities 1.0 and up”, which is normally what you want.
Chrome requires at least one PNG of 144x144 pixels. 192x192 is even better. The platform will choose the best icon to use based on the device’s screen density.
Launch Event Sequence
- Chrome launches.
- The renderer that displays the page starts up.
- Your site loads from the network (or from cache if it has a service worker).
At this point, assuming all requirements have been met, Chrome will display a prompt to the user asking to add your PWA to their home screen. By clicking the ‘Add to Home Screen’ button the user seamlessly adds the icon to the home screen. Behind the scenes Chrome processes the web manifest meta data to drive the rest of the experience.
Now anytime the user opens your PWA from the home screen, or visits a page within your PWAs scope it will render as a PWA using the display mode you chose as well as other user experience settings.
Polyfiling the Home Screen Experience on iOS and other Legacy Browsers
A common question developers and business owners ask is how to enable progressive web application features on iOS and older browsers like Internet Explorer. While all features cannot be hacked in these browsers, much of it can.
When the iPhone was released, the initial application model was the web. They created an advanced experience for web apps that included the add to home screen experience. Unfortunately, they did not make an automatic prompt experience. Who knows, if developers did not cry out for the native app model how advanced this might be today.
What we can do is still leverage this capability and use Matteo Spinelli’s Add to Home Screen library in combination with Apple’s guidelines. Doing so allows your web apps to launch from user’s home screens, with or without browser chrome.
It is important you avoid duplicating home screen prompts by not loading the Add to Home Screen library, unless needed. The simplest way I have found to determine if the polyfil is needed is feature detecting service worker support. I chose this since browsers supporting service workers have some sort of add to home screen experience. This may or may not remain true in the future, so be ready to change criteria if things change.
Without going into details, I like to dynamically load JavaScript references when a page is loaded. The process involves a series of feature detections to polyfil various requirements like Promises and the Fetch API.
- if (!'serviceWorker' in navigator) {
- //add to home screen polyfil
- scripts.unshift("js/libs/addtohomescreen.min.js");
- }
You will also need to dynamically add the Add To Home Screen stylesheet. This time, add a feature detection script to your document’s HEAD.
- <script>
- 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);
- }
- </script>
Request caching can also be polyfiled, but is outside the scope of this article. I have been using this technique for several years to build cross-platform, instant loading single page web applications.
Microsoft Edge and Internet Explorer
At this time we don’t know what Microsoft’s plans are for an add to home screen or pin to the start menu experience will look like. Once service workers ship, I expect more details to emerge.
Currently any site referencing a valid web manifest file, served via HTTPS is considered a Hosted Web App (HWA).
HWAs can be submitted to the Windows Store and have access to additional platform APIs, just like a UWP application. They have even created a site called
PWA Builder that will take any web site and convert it to a Progressive Web Application, submit it not only to the Windows Store, but also compile Cordova apps for the Apple and Google Play stores.
Benefits Await Without Polyfils
Even if you don’t polyfil the add to home screen behavior your web application will see user engagement gains on iOS. Many companies are publicly sharing their improvements in various progressive web application case studies.
Wego, an online air travel booking service, reported a 50% increase in conversions and 35% longer sessions on iOS. Mynet increased pageviews by 15% and a 23% lower bounce rate on iOS. Lancôme increased iOS sessions by 53%. These are just a small sampling of positive progressive web application case studies.
These companies are reaping the rewards of PWAs on iOS because, by nature, properly architected web sites perform better. Plus, creating a progressive web application forces you to put the customer first, not the developer. When you do this, you create a better user experience, which directly correlates to improved key performance indicators.
Don’t be dissuaded from pursuing progressive web applications because iOS and Internet Explorer don’t support the features natively. Following progressive web application guidelines forces you to deliver a user first experience that works across all platforms.
Testing the Add To Home Screen Experience in Chrome
The developer experience would not be complete without the ability to test the add to home screen experience. Chrome has added tooling which allows you to see how your web manifest file is interpreted and manually trigger the prompt.
Launch Chrome’s developer tools, F12 and select the ‘Application’ tab. There are many choices to help you debug various aspects of a progressive web application. Under ‘Application’ there is a ‘Manifest’ choice. This will display the properties of your web manifest file, including each icon. This is a quick way for you to determine if your manifest is interpreted correctly.
There is also a link to manually trigger the ‘Add to Home Screen’ experience.
![]()
Summary
Today there are fewer degrees of separation between the web and native applications. Engaging customers is key to any brand’s success. This is not limited to consumer applications, but is just as valuable for line of business web apps.
Earning a spot on the user’s home screen is sometimes compared to marriage. It is the point where the customer makes a commitment to your brand. An automated browser prompt not only surfaces users to this deeper experience, it trains them to expect it.
Since the automatic prompt is limited to progressive web applications meeting a series of technical and security requirements end users know they have a reasonable level of trust before they add your PWA to their home screen.
Creating a web manifest is simple and easy to do. The hardest part is creating an array of application icon images that satisfy each platform’s expectations.
A small time commitment for shipping progressive web applications, the web manifest file offers a big impact. The manifest drives the user experience that solidifies your relationship and how your application launches each time they engage with your brand.
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 $17 for a limited time.
- Progressive Web App – The Latest Technology Disruption Developers Must Master Today
- Making Web Sites Look Like a Native App Without the App Store,
- HTTPS - Be Secure and Not Left Behind
- Service Workers - The Web's Latest Super Power
- What Everyone Ought to Know About the Service Worker Life Cycle
- Ship Instant Loading Web Sites Using Service Worker Pre-Cache
- Who Needs a Network When Your Site Uses Service Worker Caching
- Progressive Web Application Tools and Utilities