What Is a Website Manifest and Why Do You Need it?
What Is a Website Manifest?
A website manifest is a file you add to your website that tells devices how to treat your website as a PWA (Progressive Web App) within an OS (e.g., android, windows, iOS). But why would you need this? It’s a website, the user can just access it in their browser! Let go over the reasons:
The main benefit of the manifest is that it makes it so users can install your site as an App in their OS. For mobile, this means it acts as an App on their phone they can add to their home screen. In this day and age people use their phones as their main computer and this is the most common and convenient way to quickly access information. So making it easier for them to access your site on their mobile device is a great way to keep them visiting your website. This of course ultimately results in greater engagement and also most likely more revenue depending on the nature of your site (whether selling products directly, or from advertisers on your site).
Having your site on their home screen also acts like a tiny ad that’s always on their phone. It’s there whenever they view their apps on their phone, and some may even choose to pin it if they use it a lot. Allowing your site to be installed as a PWA takes very little effort and is definitely worthwhile with the potential benefits.
Bookmarks with and without a manifest
It should be noted that users can actually add your site to their home screen even if you don’t have a manifest, but there are some distinct disadvantages there. For example, if you bookmark a site on Chrome in mobile and add it to your home screen, without a manifest it will create an icon that is just the first letter of your site’s domain. That’s it, no branding and no real indicator of what the bookmark is.
Alternatively, with a manifest you can control the branding and user experience; you can set the App icon, a proper App name, the display mode (like full screen or standalone without a browser UI), and even theme colors. In general it makes your site look and feel like a professional App rather than just a basic bookmark with a generic icon that loads into a browser.
So now that we’ve gone over why a manifest is beneficial, let’s see how to implement it.
Implementation
Implementation is relatively straightforward, depending on your configuration and goals. Here is a bare minimum configuration:
{
"name": "Full App Name",
"short_name": "App",
"start_url": "/index.html",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#000000",
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Put that in a web-accessible file on your site and name it “manifest.json”, then add these lines to your <head> tag:
<link rel="manifest" href="/manifest.json">
<link rel="apple-touch-icon" href="https://www.somesite.com/assets/icons/pwa-192.png">
Note: the second <link> tag is required by some instances of Safari on iOS.
Start URL (start_url)
The start_url tells the PWA which page to load when the App starts. You can get different behaviors depending on how you set this:
if the App should always open to the homepage, you can just set it in the manifest JSON directly.
if the App should open whatever page they were on when they installed the App, then omit the key entirely.
if the App start page should vary based on the page they were on when they installed the App, then you can implement a dynamic solution. Accomplishing that will vary greatly based on your stack and framework, but essentially what you want to do is set a route to a class that can dynamically generate the JSON at the route, ‘manifest.json’. To help visualize a use case for this, look at this example:
Say your site has international (INTL) prefixes like /us, /uk, /ca, and you want the start_url to always be the INTL site homepage (one of the aforementioned prefixes). So if the user is on /ca/privacy, and they install the App from that page, then the start_url should be ‘/ca’. Since this needs some string parsing based on the current URL, the easiest way to do this would be to pass the current URL as a query string, e.g. (in PHP),
<link rel="manifest" href="/manifest.json?loc=<?=$_REQUEST_URI?>">
The route’s handler would then parse the query string and execute logic as needed to provide the desired start_url.
Icons
Another great aspect of the manifest is that it allows you to provide the icon that will be used for the App on the home screen. Benefits include easy identification on the home screen and brand recognition. One note of caution here is that you don’t want to use images with transparency. If your logo is red and they install on their home screen with a lot of red in the background, your app icon will be hard to see. An App icon should always be a shape with a solid color background and then a logo that contrasts well against it.
Advanced Configuration
A manifest will also allow you to install a site as a non-mobile application, but that’s really a limited use-case. If you wanted, and the manifest supports it, you can actually install a webpage as an App in Windows. It will appear on the start menu and behave like an installed app. But, this would require an advanced manifest configuration that involves defining a Service Worker in the manifest. As mentioned, this use case is fairly rare and most users never use it or even know the functionality exists. In practice, desktop users just launch their browser and go to a bookmark within the browser, or create a shortcut on their desktop which they can also pin wherever they want.
There is also a “Richer” install experience you can configure, but it’s not required to get the benefits discussed so far so we’ll skip it. It’s really not necessary except again for some special use cases. So don’t worry if you see messages in the devtools Manifest section’s ‘Errors and warnings’ that start with “Richer PWA Install UI”, you can safely ignore those.
Verifying Implementation
Once you have everything set up, how do you verify it’s working? There is a quick way you can check during development, and that’s through Chrome’s devtools. Load the site, hit F12, then go to the 'Application' tab and then the ‘Manifest’ option in the left nav.
And of course the final tests will be by deploying the manifest to your site and then jumping on your phone and installing your new website app! Try installing it as a bookmark and as an app. The bookmark version will use your manifest icon, and the App version will behave just like a native mobile App.