With the increasing popularity of progressive web apps (PWA), mainly due to their powerful features, capable of creating app-like experiences, it is important to get your basics right. In this post, we will deep dive into a PWA's manifest file.
This file lets the browser know more about your app, and help configure it when it is installed on the user's desktop or mobile device. Among other things, a manifest file provides information about the app's name, the URL or which icons the users will see.
A web manifest file is a JSON text file, commonly named manifest.json, although it could also be defined as .webmanifest as per its own specification.
It is supported by Chrome, Edge, Firefox, UC Browser, Opera, and the Samsung browser. Safari offers partial support. For more information about support please check this browser compatibility table.
Contents
A web manifest file can contain the following keys:
| Key | Type | Mandatory |
|---|---|---|
| background_color | String | No |
| categories | String | No |
| description | String | No |
| dir | String | No |
| display | String | No |
| display_override | Array | No |
| iarc_rating_id | String | No |
| icons | Array | Yes |
| lang | String | No |
| name | String | Yes |
| orientation | String | No |
| prefer_related_applications | Boolean | No |
| protocol_handlers | Array | No |
| related_applications | Array | No |
| related_applications | Array | No |
| scope | String | No |
| screenshots | Array | No |
| short_name | String | No |
| shortcuts | Array | No |
| start_url | String | No |
| theme_color | String | No |
Basically, it will look very similar to the following example:
{
"short_name": "Notificare",
"name": "Notificare - Customer Engagement Platform",
"start_url": "/",
"background_color": "#232c2a",
"description": "Discover the platform that delivers the most engaging messages and interactions. Because every superhero needs a sidekick.",
"display": "standalone",
"orientation": "portrait-primary",
"icons": [
{
"src": "assets/images/icon-36x36.png",
"sizes": "36x36",
"type": "image/png",
"density": "0.75"
},
{
"src": "assets/images/icon-48x48.png",
"sizes": "48x48",
"type": "image/png",
"density": "1.0"
},
{
"src": "assets/images/icon-72x72.png",
"sizes": "72x72",
"type": "image/png",
"density": "1.5"
},
{
"src": "assets/images/icon-96x96.png",
"sizes": "96x96",
"type": "image/png",
"density": "2.0"
},
{
"src": "assets/images/icon-144x144.png",
"sizes": "144x144",
"type": "image/png",
"density": "3.0"
},
{
"src": "assets/images/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"density": "4.0"
}
]
}Using a manifest file
To deploy a web manifest file, you will simply need to include a <link> element in the <head> of your HTML pages, as follows:
<link rel="manifest" href="manifest.json">The browser will then use its contents whenever it runs display your web application. But let's deep dive into each key you can provide in your manifest file.
background_color
This optional property will tell the browser which color to use as the background color of your page, before any stylesheet is loaded. Obviously, it should match the background color you use in your CSS.
"background_color": "#FF0000"categories
This property is also optional, and when provided, it should contain an array of strings (lowercase) with the categories the web app belongs to. There isn't a strict format for these categories but W3C maintains a list of standard categories you should use.
"categories": ["lifestyle", "music", "news"]description
This property can be used to provide more information about your web application. It can also be displayed in different directions when used in combination with lang and dir.
"description": "Discover the platform that delivers the most engaging messages and interactions. Because every superhero needs a sidekick."dir
This property defines the direction of the text of other properties (name, short_name and description). It can be set as auto, ltr or rtl.
"dir": "rtl",
"lang": "ar",
"description": "اكتشف النظام الأساسي الذي يقدم الرسائل والتفاعلات الأكثر جاذبية. لأن كل بطل خارق يحتاج إلى مساعد."display
This property will define how much of the browser's UI is shown to the user. The browser will follow a pre-defined fallback chain, fullscreen → standalone → minimal-ui → browser, where browser is the default when none is provided.
With fullscreen, all the available display area will be used.
When you use standalone, the app will look and feel like a native application. In this mode, the browser will exclude UI elements that control the navigation but might include a status bar.
With minimal-ui, the application will look and feel like a standalone application but will contain UI elements for controlling navigation.
Finally, when browser or none is provided, the application will open in a conventional browser tab or window.
"display": "standalone"display_override
This property can be used to override the fallback sequence provided in display. In some advanced use cases, you simply want to tell the browser what sequence to use and the first supported mode will be used.
You use this property by providing an array of display modes.
All display modes (as described in display) are available. Additionally you can also use window-controls-overlay. This display mode is only applied when the application is in a separate PWA window and on a desktop operating system.
The app will then use the Window Controls Overlay feature, where the full window will be available for the web app content and the window-controlling elements (maximize, minimize, close, etc) are shown on the top of the web content.
"display_override": ["fullscreen", "minimal-ui"],
"display": "standalone",iarc_rating_id
This property will define the IARC certification code (International Age Rating Coalition). It is used to determine which ages the web application is appropriate for.
"iarc_rating_id": "e84b072d-71b3-4d3e-86ae-31a8ce4e53b7"icons
This property is mandatory and should be used to provide a list of images that can serve as application icons or splash screens.
Each image object can contain the following properties: sizes, src, type and purpose.
"icons": [
{
"src": "assets/images/icon-36x36.png",
"sizes": "36x36",
"type": "image/png"
},
{
"src": "assets/images/icon-48x48.png",
"sizes": "48x48",
"type": "image/png"
},
{
"src": "assets/images/icon-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
]lang
When provided, this property should contain a single language tag. It will define the primary language of other properties (name, short_name and description) and together with dir, it will determine the direction of these properties.
"lang": "en-US"name
This property is mandatory and will define the name of the application as it should be shown to the user. This property can be displayed in different directions based on the values of lang and dir.
"name": "Awesome application"orientation
This property defines the orientation of all the web app's top level browsing contexts. In modern browsers, this is usually a tab, window or even parts of a web page, like an iframe.
Orientation can use one of the following values: any, natural, landscape, landscape-primary, landscape-secondary, portrait, portrait-primary and portrait-secondary.
"orientation": "portrait-primary"prefer_related_applications
This boolean property tells the browser to suggest the installation of the native applications (if supported) listed in related_applications, instead of web app.
"prefer_related_applications": trueprotocol_handlers
This array of objects will define the protocols that an web app can register and handle. When supported by the operating system, a web app will be associated and invoked when users click a hyperlink with a specific URL Scheme.
"protocol_handlers": [
{
"protocol": "web+shop",
"url": "/shop?q=%s"
}
]related_applications
This property should be an array of objects specifying native applications that are installable or accessible to users in specific platforms.
In combination with prefer_related_applications, it can be used to suggest the user to install the native application instead of the web app.
"related_applications": [
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=re.notifica.dashboard&hl=en_US&gl=US",
"id": "re.notifica.dashboard"
}, {
"platform": "itunes",
"url": "https://apps.apple.com/us/app/notificare-dashboard-app/id1072377111"
}
]scope
This property will define the navigation scope of the web app. It will restrict the web pages that can be viewed and open any link, outside this scope, in a browser tab or window.
"scope": "https://app.notificare.com/"screenshots
This optional property is intended to be used by PWA app stores to showcase the web app.
"screenshots" : [
{
"src": "/assets/screenshots/img1.png",
"sizes": "1280x720",
"type": "image/png",
"platform": "wide",
"label": "Homepage"
},
{
"src": "/assets/screenshots/img2.png",
"sizes": "1280x720",
"type": "image/png",
"platform": "wide",
"label": "Features"
}
]short_name
This property will be used when there isn't enough space to display the property name. Just like name, this property can be display in different directions when used in combination with lang and dir.
"short_name": "Notificare"shortcuts
This property defines a list of tasks that can be quickly presented to a user. Operating systems may use this property to display a context menu to users and when any of these menu items are clicked, it will take them to whatever is provided in the url property.
"shortcuts" : [
{
"name": "Inbox",
"url": "/inbox",
"description": "Your in-app messages"
},
{
"name": "Take a Photo",
"url": "/take/photo"
}
]start_url
This property will define the starting page when the web app is launched. A browser can however ignore this suggestion and allow the user to modify it at the install time.
"start_url": "/start"theme_color
This property defines the default theme color for the web app. Operating systems may use it to customize any web app related context.
"theme_color": "#232c2a"Learn more
As you can see, a web manifest is a fundamental part of a great PWA. More information about web manifest files can be found in the W3C specification.
As always, we hope you liked this article and if you have anything to add, maybe you are suited for a Developer position in Notificare. We are currently looking for several positions, so please check out our careers page.