Install your web app on a user’s device

Francesco Leardini

6 min readJun 23, 2019

In the first article we discovered the PWAs potential and how they differ from native apps.

If you missed it, go and have a look, you might find some unknown details, even if you are already familiar with PWAs!

Web App Manifest

MDN docs give a great and clear definition:

The web app manifest provides information about a web application in a JSON text file, necessary for the web app to be downloaded and be presented to the user similarly to a native app (e.g., be installed on the home screen of a device, providing users with quicker access and a richer experience).

Typically we place the web app manifest at the root of our web application. We can name it: manifest.json or manifest.webmanifest and serve it with the media type application/manifest+json.

To associate a manifest to a web application, we use the <link> tag in the <head> section of an HTML document (usually index.html):

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

The snipped above indicates to the user agent that the metadata of the manifest must be adopted instead of the one in the Document. In case some properties are not set correctly though, the user agent will fallback to the Document metadata.

The request for the manifest is made without any credentials (even if it is on the same domain). So if the manifest requires credentials, we have to add the attribute crossorigin="use-credentials":

<head>
  <link rel="manifest" href="/manifest.webmanifest" crossorigin="use-credentials">
</head>

From MDN web docs:

If the attribute is not present, the resource is fetched without a CORS request (i.e. without sending the Origin HTTP header), preventing its non-tainted usage. If invalid, it is handled as if the enumerated keyword anonymous was used.

I had once an issue in a project, where the manifest.json file was generating a generic error, while on localhost everything was working perfectly:

Manifest: Line: 1, column: 1, Unexpected token.

Quite a generic description 😟

The only thing I had to do, was adding the crossorigin attribute and the manifest file was then correctly served in the browser without errors anymore.

Manifest files are supported by almost any browser, Safari is currently working on adding support.

File structure

An example of web app manifest can look like the following:

{
  "short_name": "MyCoolPWA",
  "name": "My cool Progressive Web App",
  "start_url": "/?source=pwa",
  "display": "standalone",
  "icons": [
    {
      "src": "/images/icons-144.png",
      "type": "image/png",
      "sizes": "144x144"
    },    
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "orientation": "landscape",
  "description": "A simple experiment with PWAs",
  "background_color": "#3367D6",
  "theme_color": "#3367D6"
  "scope": "/",
}

Let’s break down the file and describe it step by step.
Some of the properties are mandatory to make the add to home screen, A2HS in short, dialog to appear (we will describe it later in this post).

The fields needed are:

name/short_name: the value used will be displayed under the application icon once installed on the user’s device. In Chrome, the app name is also used in the splash screen, displayed before accessing the PWA. Short name is used instead of name if there is not enough space to display the whole value.
start_url: is the path to the assets that should be loaded when the app is launched. This is very useful as we want our application to start always from the same page (eg. home page), rather than from the last visited one in the app.
You might wonder why we have a query string in the example above. By adding a query string to the url we allow our web analytics tools to determine how many users accessed the web app via the icon on the home screen. This gives us some more information on users behaviour.
display: Specifies how the app should be displayed. There are different values possible:

browser: provides a standard browser experience, exactly the same as we would access any website with a mobile device.

standalone: this option is quite interesting as the application is opened in an independent window, separated from the browser one making our PWA look like it would be a native app. Moreover some UI browser elements, like the address bar, are not displayed anymore.

fullscreen: as the name tells, our PWA will use the whole screen of the device. No UI browser elements are rendered. This option is particularly suited for game or multimedia apps.

icons: Indicates the icons for the browser to use when representing the app. As a minimum we have to provide an icon with at least 144px resolution.
Chrome suggests to have two: one with 192px and one with 512px resolution. Chrome will then take care to scale the icons according to the user’s device. Anyway the best approach to ensure we deliver a pixel perfect experience to our users is to identify which are our target devices and then add icons with the relative resolution.
background_color: sets the background color of our app. If we add the PWA to the home screen using Chrome, the background colour will be used also for the splash screen.

There are also other properties, optional, but considered recommended:

orientation: lets us specify whether the application should be displayed in portrait (vertical) or landscape (horizontal) mode. The latter is usually better for games/media apps.
theme_color: on mobile devices it sets the theme color surrounding the site. On desktop, the theme color is used to style the title bar.
description: describes our app.
scope: defines the navigation scope of our website’s context. If the user navigates outside the scope, it returns to a normal web page inside a browser window.

If we do not want to create the manifest by hand, we can use a manifest generator. This is a simple tool that provides already a manifest skeleton, where we have only to fill the properties with the values we want.

Add to home screen dialog (A2HS)

To display an A2HS dialog not only the manifest properties must be correctly initialised. We also need to serve the app through a secure connection (HTTPS). Chrome in particular requires also the app to have a service worker registered.
If all these points are fulfilled, the browser will show the A2HS dialog.

If the user closes the dialog without accepting to install the app, the dialog will not be appear again for around 90 days.
On the other side, if the app is added to the home screen, it will look like exactly as a native app, using one of the icons we defined in the manifest file. By looking at the icon, we can not say whether there is a native app or a PWA behind it.

Test the manifest

In order to verify that our manifest is setup correctly we can use Chrome DevTools. Open the Application tab and access the Manifest section on the left side.

We can see that the properties and icons defined in our manifest file are reported in this section (here the dev.to manifest file).
If you can see your manifest properties in this tab as well, then you are set! You deployed correctly the web app manifest to your PWA 🎉

You can also use a manifest validator to validate your manifest.

In the next post we’ll discuss about service workers and how we can serve our app even when the user is offline:

Originally published at https://dev.to on June 23, 2019.

Install your web app on a user’s device

Web App Manifest

File structure

Add to home screen dialog (A2HS)

Test the manifest

Written by Francesco Leardini