Simple Web Development: How to implement a Web App Manifest

Implementing and including a Web App Manifest is at worst a nice addition to your website or PWA, and at best a great extension of your applications functionality and how users interact with it.

The web app manifest is a simple JSON file that tells the browser about your web application and how it should behave when ‘installed’ on the user’s mobile device or desktop.

When included, users can pin your site to their homescreens and start using it much like an installed app would be used. And the Manifest let’s your control exactly what and how said user would see your site after opening it from their homescreen.

Especially PWAs or websites with service workers (building on top of your offline capable application) can profite from using this easy and rather quick to implement JSON:

{
"name": "Magellan Code & Design Consulting",
"short_name": "Magellan",
"icons": [
{
"src": "/assets/images/pixel/appicon/m-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/assets/images/pixel/appicon/m-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": "/?source=pwa",
"scope": "/",
"display": "standalone",
"background_color": "#1b1b1c",
"theme_color": "#1b1b1c"
}

The name and short_name attributes are used depending on their character length respectively, where the latter is often used on homescreens, were space is limited.

Two default icon sizes should also be implemented, so that devices can resize to the needed resolution.

The start URL defines what page is opened first, when your application is started. In this case, I simply added an attribute to my root folder so I can easily analize how many users have pinned and used my app.

The scope defines where your app lives and where it ends. Usually the root folder, may be one of your subfolders.

For display I have chosen standalone, which displays your app without browser UI in a seperate window, much like any installed (native) app.

The theme and background color are used in different places, like to color your app icon and splash screen.

In Chrome:

When your app first launches, it can take a moment for the browser to spin up, and the initial content to begin rendering. Instead of showing a white screen that may look to the user like the app is stall, Chrome will show a splash screen, until the first paint.

Don’t forget to implement the manifest in the head meta area:

link(rel=”manifest” href=”manifest.json”)

For a deeper understanding, read the documentation.


But wait, there’s more!

Adding only the manifest isn’t sufficient (yet), as some major mobile browers don’t fully support it yet. iOS Safari needs some additional information in the meta section of your DOM:

meta(name="theme-color" content="#1b1b1c")
meta(name='mobile-web-app-capable' content='yes')
meta(name='apple-mobile-web-app-capable' content='yes')
meta(name='application-name' content='Magellan')
meta(name='apple-mobile-web-app-status-bar-style' content='black')
meta(name='apple-mobile-web-app-title' content='Magellan')
link(rel='icon' sizes='192x192' href='/assets/images/pixel/appicon/m-192.png')
link(rel='apple-touch-icon' href='/assets/images/pixel/appicon/m-192.png')
meta(name='msapplication-TileImage' content='/assets/images/pixel/appicon/m-144.png')
meta(name='msapplication-TileColor' content='#1b1b1c')
meta(name='theme-color' content='#1b1b1c')
meta(property='og:title' content='Magellan')
meta(property='og:type' content='website')
meta(property='og:image' content='/assets/images/pixel/appicon/m-192.png')
meta(property='og:url' content='https://bymagellan.co/')

This example also includes information for Microsoft’s Edge Browser. You can leave that out if you don’t wish to support it. It will soon be Chromium anyway.

Make sure to use the same theme color and icons that you would use in the Manifest.


Adding this to your offline capable application makes it easily available on users homescreens and can increase usage and User Experience ratings.


Testing your Manifest in Chrome Dev Tools

First, make sure your Manifest is registered by the browser and all entered values are registered.

By auditing your site through Lighthouse, which is built into the Chrome Dev Tools “Audit” tab, you can make sure you meet all the instalability (and PWA) requirements.

🕶 Some more examples

Website opened through pinned app icon
Prompt appearing in Google Chrome on Android Devices
Chrome install Popup — Windows 10
Pinned and opened insalled App (through Chrome) — Windows 10

Great websites to try this out before you start:

Google Flights

GitHub

The Air Horner

Magellan Code & Design Consulting — Portfolio Website (from this example)


If you’re interested in seeing the exact code of the example used in this article, head over to GitHub to see the full commits (Commits on Feb 11, 2019).