Add a Web App Manifest for an Ecommerce PWA

Creating and loading a web app manifest file is among the first steps toward transforming an ecommerce website into a progressive web app that can be installed on a mobile device.

The term “progressive web app” or “PWA” describes a website that employs practices and modern APIs to provide users with an experience that is similar in quality and capability to a native mobile or desktop application.

One of PWA’s greatest tricks is that it can be installed on a mobile device, placing an icon on the home screen. This is true even for Apple’s iOS after version 11.3.

A web app manifest file is the first step toward a progressive web app, which can be installed on a mobile device, similar to a native application. Photo: William Hook.

An ecommerce store can have its full product catalog directly on a customer’s mobile phone where shopping is just a tap away. The first step, again, is a web app manifest file.

Required Members

In JavaScript Object Notation (JSON), a property is a key-value pair. The key is the name of the property. The value is the information or value of the property. This value may be text, a set of values called an array, or an object, which may have properties of its own.

Here is an example of a text value. The short name for this PWA is “Pan Finder.”

{ "short_name" : "Pan Finder" }

The web app manifest file specification allows for 18 properties or keys that can provide information for how to display and load a PWA on a mobile device. In the context of a manifest file, these properties are sometimes called members. Generally, just five of these properties or members are required: name, short-name, icons, start_url, display.

name is the name of your PWA. It could be displayed under your app icon on the home screen and in other places in the mobile operating system.

It doesn’t have to be the same as the name of your ecommerce business or your website. But it may be. If you had an online cookware store called “Maggie Mae’s Pots and Pans,” you could use your full business name or come up with an app name such as “Pot and Pan Finder.”

{ 
    "name" : "Pot and Pan Finder",
}

As a rule, keep the name short.

short_name is a fallback when the name property is too long to fit. It, too, may appear under your app’s icon on the home screen. The recommendation is 20 characters or fewer. But 10 characters may be best. “Pan Finder,” as an example, is exactly 10 characters.

{ 
    "name" : "Pot and Pan Finder",
    "short_name" : "Pan Finder"
}

icons. The icons member’s value is an array or set of objects that represent your application’s icon images. Mobile devices routinely ask for a set of image icons. iOS apps typically require several.

• 120 x 120 pixels for an iPhone.
• 152 x 152 pixels for an iPad and iPad Mini.
• 167 x 167 pixels for an iPad Pro.
• 180 x 180 pixels for an iPhone.

Google’s Chrome browser on iOS or Android requires at least two more.

• 192 x 192 pixels.
• 512 x 512 pixels.

In the web app manifest file, the set of icons is an array. It is designated with an opening and closing bracket (sometimes called a square bracket).

"icons" : [ ]

Individual image information is stored as an object with three or four properties:

• The src property’s value is the path to the icon image.
• The sizes property describes the image’s dimensions.
• The type property is a hint at the kind of image file the icon is stored as.
• The i property can provide information about how the icon may be used. But I will omit it for this example.

In JSON, an object is indicated with a curly brace. So each set of icon information is placed within an opening and a closing curly brace.

"icons" : [ 
    {
       "src" : "/imgs/icon192.png",
       "type" : "image/png",
       "sizes" : "192x192"
    }

]

To add the information for another icon, put a comma after the closing curly brace from the previous icon’s information.

"icons" : [ 
    {
       "src" : "/imgs/icon192.png",
       "type" : "image/png",
       "sizes" : "192x192"
    },
    {
       "src" : "/imgs/icon512.png",
       "type" : "image/png",
       "sizes" : "512x512"
    }
]

This is what the manifest file would look like so far.

{ 
    "name" : "Pot and Pan Finder",
    "short_name" : "Pan Finder",
    "icons" : [ 
       {
          "src" : "/imgs/icon192.png",
          "type" : "image/png",
          "sizes" : "192x192"
       },
       {
          "src" : "/imgs/icon512.png",
          "type" : "image/png",
          "sizes" : "512x512"
       }
    ]
}

start_url. The start_url member should have the path to the starting page for the application. If this is your website’s home page, for example, the value of this could be a slash (/).

{ 
    "name" : "Pot and Pan Finder",
    "short_name" : "Pan Finder",
    "icons" : [...],
    "start_url" : "/"
}

Although the specification does allow a URL such as https://example.com/, at the time of writing the Chrome browser will only accept the relative path, i.e., the slash shown above.

display. The display member tells the mobile device’s operating system how the developer would like the application to display. Although the value for this property is text, there are only four available display modes.

• fullscreen. Your app dominates the display, but be careful as there would be no back button.

• standalone. This is similar to a native application. The browser running your PWA will not have navigation in some cases. Your app would have its own window.

• minimal-ui. This is similar to standalone but includes the basic browser navigation.

• browser. Your app will open in a new browser tab.

{ 
    "name" : "Pot and Pan Finder",
    "short_name" : "Pan Finder",
    "icons" : [...],
    "start_url" : "/",
    "display" : "minimal-ui"
}

Recommended Members

In addition to name, short_name, icons, start_url, and display, it’s a good idea to include at least four more properties or members.

• description. Exactly how it sounds.

• scope. Limits where a user can go with the PWA window open. So this could prevent someone from loading your app, but using your app window to navigate to Walmart’s website. Use your site’s full URL or just a slash to limit the scope to your site.

• background_color. This member should match the CSS background-color property for your landing page (i.e., the start_url page). The browser should use this color to generate a splash screen for your app when it loads.

• theme_color. Sets the color used to display the app. On Android, this is the task switcher, as an example.

Include the Manifest File

A completed web app manifest file will look similar to the JSON code shown below and should be saved with a .json or .manifest file extension.

{ 
    "name" : "Pot and Pan Finder",
    "short_name" : "Pan Finder",
    "icons" : [
       {
          "src" : "/imgs/icon192.png",
          "type" : "image/png",
          "sizes" : "192x192"
       },
       {
          "src" : "/imgs/icon512.png",
          "type" : "image/png",
          "sizes" : "512x512"
       }
    ],
    "start_url" : "/",
    "display" : "minimal-ui"
}

The manifest file should be saved in your website’s root directory. So if your domain were example.com, the manifest file would be at example.com/manifest.json. This can be signified with a relative path, as in /manifest.json.

This file can then be linked in the head section of an HTML document.

<link rel="manifest" href="/manifest.json">

When the HTML document is loaded, the browser should be able to find and read your web app manifest file.

Web App Manifest File Resources

• W3C Web App Manifest specification
• Mozilla Developer Network Web App Manifest article
• “Add a Web App Manifest” article by Pete LePage
• “Discover what it takes to be installable,” by Pete LaPage
• “Progressive Web Apps 101: the What, Why and How,” by Shruti Kapoor
• “Are PWAs The Way? Everything You Need To Know About Progressive Web Apps For Ecommerce,” by Jamie Maria Schouren