Making Web Sites Look Like Native Apps Without the App Store

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.

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.

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.

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.