The Power of PWA Manifest: Unlocking the Potential of Progressive Web Apps

In the ever-evolving digital landscape, businesses are constantly seeking innovative ways to enhance user experience and engage their audience effectively. One of the most promising advancements in web technology is the concept of Progressive Web Apps (PWAs). These web applications combine the best features of traditional websites and native mobile apps, offering users a seamless and immersive experience across multiple devices. To harness the full potential of PWAs, developers rely on a crucial component called the PWA manifest. In this article, we will explore the significance and all elements of the PWA manifest and its role in optimizing Progressive Web Apps for superior performance, discoverability, and user satisfaction.

What Is a PWA Manifest?

The PWA manifest is a JSON (JavaScript Object Notation) file that provides essential information about a Progressive Web App (PWA). It serves as a blueprint for the browser to understand and interact with the web application, enabling it to behave more like a native app. The manifest contains various parameters that define the app’s appearance, functionality, and behavior when installed on a user’s device.

In simpler terms, the PWA manifest is like a set of instructions that tells the browser how the app should look and behave on different devices. It includes details such as the app’s name, start URL, display mode, icons, theme color, and other important information that helps create a consistent and immersive user experience.

Purpose and Role of the Manifest File in PWAs

The manifest file in Progressive Web Apps (PWAs) serves an essential purpose and plays a crucial role in enhancing the overall functionality and user experience. Let’s delve into its purpose and role in more detail:

Purpose of the Manifest File

The primary purpose of the manifest file in PWAs is to provide a standardized way of defining the app’s metadata and configuration. It allows developers to specify important details about the app, such as its name, icons, start URL, display mode, theme colors, and other essential properties. By encapsulating this information in a manifest file, PWAs become self-contained and can be easily installed and launched on users’ devices, just like native apps.

Role of the Manifest File

The manifest file in PWAs serves the purpose of encapsulating important metadata and configuration details. It plays a crucial role in facilitating app installation, defining the app’s appearance and behavior, enabling offline functionality, and delivering an engaging user experience:

• App Installation: The manifest file facilitates the installation of PWAs by enabling users to add them to their home screens or app launchers. When users visit a PWA-enabled website, the browser prompts them to install the app. The manifest file provides the necessary information for the browser to create an app shortcut on the home screen, ensuring easy access.
• App Appearance and Branding: The manifest file allows developers to define the app’s appearance, including the app’s name, icons, and colors. By specifying icons of different sizes and resolutions, developers can ensure that the app’s branding remains consistent across various devices and platforms.
• Display Modes: The manifest file lets developers define the app’s display mode, which determines how the app appears and behaves when launched. Options include fullscreen, standalone, minimal-ui, and browser. This flexibility allows developers to tailor the user experience based on the intended use case and device.
• Offline Functionality: The manifest file can also include settings for enabling offline functionality in PWAs. By utilizing service workers and caching strategies, PWAs can continue to work even when the user’s device has limited or no internet connectivity. The manifest file can specify which resources should be cached, enabling offline access to essential app content.
• Engaging User Experience: The manifest file plays a vital role in providing a consistent and immersive user experience. By defining the app’s visual and behavioral characteristics, developers can create an engaging and seamless interface. This can include settings such as the app’s theme colors, background color, splash screen, and more.

Key Fields of the PWA Manifest

The initial set of fields in the PWA manifest represents the essential information about your Progressive Web App (PWA). These fields play a crucial role in constructing the PWA’s icon and window, as well as determining its startup behavior. They include:

name

The name field in the PWA manifest is a string that represents the name of the web application, which is typically displayed to the user. This can include scenarios where the application is listed among other applications or where it serves as a label for an icon.

The name field serves as the accessible name of an installed web application. It provides a recognizable and descriptive label for users, making it easier for them to identify and interact with the application. Whether displayed in an app launcher or a list of installed apps, the name field helps users quickly locate and access the web application they desire.

short_name

The short_name field in the PWA manifest is a string that represents a shortened version of the web application’s name. It is specifically designed for situations where there is limited space available, making it difficult to display the full name of the web application.

The purpose of the short_name field is to provide a concise and compact label that can be used in instances where there is insufficient space to display the complete name of the web application. This can include scenarios such as displaying the application’s name on the device’s status bar or in contexts where space is limited, such as app launchers or navigation menus.

scope

The scope field in the PWA manifest is a string that defines the navigation scope of the web application’s application context. It determines the range of URLs within which the web application can operate.

To process the scope field, the following steps are taken using the ordered maps json and manifest:

• Set the manifest[‘scope’] field by parsing the string “.” with manifest[‘start_url’] as the base URL.
• If json[‘scope’] is an empty string, then stop processing.
• Parse the string json[‘scope’] with the URL of the manifest as the base URL, and assign the result to the variable scope.
• If the parsing of the scope string results in an error, stop processing.
• Remove the query and fragment components from the scope.
• If the manifest[‘start_url’] is not within the scope range, stop processing.
• Otherwise, set manifest[‘scope’] to the value of scope.

icons

The icons field in the PWA manifest is an array of icon objects. Each icon object contains properties such as src, type, sizes, and optional purpose fields, which collectively describe the images that represent the PWA.

The icon of your PWA serves as its visual identity across users’ devices when installed. It is crucial to define at least one icon to ensure a consistent and recognizable representation. By utilizing the icons property as a collection of icon objects, you can define multiple icons in different formats, providing the best icon experience for your users. Each browser will select one or more icons based on its requirements and the operating system on which it is installed, giving priority to the icons that closely match the specified criteria.

If you are selecting only one icon size, it is recommended to choose 512 by 512 pixels. However, it is advisable to provide additional sizes, including 192 by 192, 384 by 384, and 1024 by 1024 pixel-sized images, to ensure compatibility with different devices and platforms.

Here is an example of the icons field in the PWA manifest:

json
Copy code
"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

By providing the icons field with appropriately sized images, you ensure that your PWA meets the installation criteria on various platforms. Failure to provide icons or icons that do not meet the recommended sizes may result in installation issues on some platforms. In such cases, the platform may generate an automatic icon, such as using a screenshot of the PWA or a generic icon. To maintain control over the visual representation of your PWA, it is best to provide icons that adhere to the recommended specifications.

start_url

The start_url field in the PWA manifest is a string that represents the preferred URL that the developer intends the user agent to load when the user launches the web application. This typically occurs when the user clicks on the web application’s icon from the device’s application menu or home screen.

It’s important to note that the start_url field is advisory in nature, and the user agent has the discretion to either ignore it or provide the end-user with the option to choose whether or not to use it. Additionally, the user agent may allow the end-user to modify the URL, for example, when creating a bookmark for the web application or at any time thereafter.

To process the start_url field, the following steps are taken using the ordered maps json and manifest, along with the URLs manifest URL and document URL:

• Set the value of manifest[‘start_url’] to the URL of the document.
• If json[‘start_url’] does not exist or is not a string, stop processing.
• If the type of json[‘start_url’] is not a string or if it is an empty string, stop processing.
• Parse the string value of json[‘start_url’] using the manifest URL as the base URL, and assign the result to the variable start URL.
• If parsing the start URL results in an error, stop processing.
• If the start URL is not from the same origin as the document URL, stop processing.
• Otherwise, set the value of manifest[‘start_url’] to the start URL.

display

The display field in the PWA manifest represents the developer’s desired display mode for the web application. It is a string value that can be set to one of the following options: fullscreen, standalone, minimal-ui, or browser. Each display mode instructs the operating system on how to render the PWA window. You can find more information about these display modes in the App Design chapter, but the standalone mode is commonly used for most use cases.

To process the display field in the manifest, the following steps are taken using the ordered maps json and manifest:

• Set the value of manifest[‘display’] to browser by default.
• If json[‘display’] does not exist or is not a string, stop processing.
• If the display mode list does not contain the value specified in json[‘display’], stop processing.
• Set the value of manifest[‘display’] to the value specified in json[‘display’].

orientation

The orientation field in the PWA manifest is a string that specifies the default screen orientation for all top-level browsing contexts of the web application. It determines how the application is initially displayed in terms of screen orientation. The possible values for the orientation field are defined by the OrientationLockType enum, and they include any, natural, landscape, portrait, portrait-primary, portrait-secondary, landscape-primary, and landscape-secondary.

If the user agent supports the value specified in the orientation field as the default screen orientation, it will be used throughout the lifetime of the web application, unless overridden by other means at runtime. This means that whenever the orientation is unlocked or the top-level browsing context is navigated, the user agent must return the screen orientation to the default specified in the orientation field.

It’s important to note that certain UI/UX considerations and platform conventions may restrict the use of certain screen orientations together or in specific display modes. The decision of which orientations and display modes can be used together is left to the discretion of the implementers. For example, in some user agents, it might not be logical to change the default screen orientation of an application while it is in browser display mode.

To process the orientation field in the manifest, the following steps are taken using the ordered maps json and manifest:

• If the orientation field does not exist or is not a string in json, stop processing.
• If the orientation field in json does not contain any of the valid orientation values, stop processing.
• Set the value of manifest[‘orientation’] to the value specified in json[‘orientation’].

id

The id field in the PWA manifest is a string that serves as the unique identifier for the application. The identity is represented in the form of a URL and must have the same origin as the start URL of the application.

User agents utilize this identity to uniquely identify the application universally. When a user agent encounters a manifest with an identity that does not correspond to an already-installed application, it should treat that manifest as a description of a distinct application, even if it is served from the same URL as another application. 

Conversely, when the user agent encounters a manifest where the id field is equal to the identity of an already-installed application (excluding the fragment portion of the URL), it should interpret it as a signal that this manifest is a replacement for the previously installed application’s manifest, rather than a distinct application, even if it is served from a different URL.

To process the id field in the manifest, the following steps are taken using the ordered maps json and manifest:

• Set the value of manifest[‘id’] to the value of manifest[‘start_url’].
• If the type of json[‘id’] is not a string, stop processing.
• If json[‘id’] is an empty string, stop processing.
• Let base origin be the origin of manifest[‘start_url’].
• Parse the string value of json[‘id’] using “base origin” as the base URL, and assign the result to the variable id.
• If parsing id results in an error, stop processing.
• If id is not from the same origin as manifest[‘start_url’], stop processing.
• Set the value of manifest[‘id’] to the value of id.

Recommended Fields of the PWA Manifest

The following set of fields are not required for the installability of your Progressive Web App (PWA), but they play a crucial role in enhancing the overall user experience:

theme_color

The theme_color field in the PWA manifest serves as the default theme color for the application context. The concept of a theme color is defined in the [HTML] specification.

If the user agent honors the value specified in the theme_color field as the default theme color, it will be applied to all browsing contexts where the manifest is applied. However, a document can override the default theme color by including a valid [HTML] meta element with a name attribute value of theme-color.

It’s important to note that the user agent may choose to ignore the alpha component of the theme color based on the context. In most environments, the theme color cannot be transparent.

Implementors have the flexibility to override the value defined by the theme_color field to support the prefers-color-scheme feature, which allows for adaptive theming based on the user’s preferred color scheme.

related_applications

A related application refers to an application that is accessible within the underlying application platform and has a connection or relationship with the web application.

The related_applications field in the PWA manifest lists these related applications and serves as an indication of the relationship between the web application and these related applications. It’s important to note that this relationship is unidirectional, and unless a listed application explicitly claims the same relationship, the user agent must not assume a bi-directional endorsement.

The related_applications field can be utilized in various scenarios. For example, a crawler could use this information to gather more details about the web application, or a browser could suggest a listed application as an alternative when a user wants to install the web application.

To process the related_applications field in the manifest, the following steps are taken using the ordered maps json and manifest:

• Create a new list called relatedApplications.
• Set the value of manifest[‘related_applications’] to the relatedApplications list.
• If json[‘related_applications’] does not exist or is not a list, stop processing.
• For each app in json[‘related_applications’]:
  • If both app[‘id’] and app[‘url’] are present:
    • Set app[‘url’] to the result of processing the url member of an application, given the value of app[‘url’].
    • Append app to the relatedApplications list.
• Set relatedApplications to the value of the manifest[‘related_applications’] field.

prefer_related_applications

The prefer_related_applications field in the PWA manifest is a boolean value that serves as a hint to the user agent, indicating a preference for related applications over the web application itself. When the prefer_related_applications field is set to true, it suggests to the user agent that if it intends to suggest installing the web application, it might be more appropriate to recommend installing one of the related applications instead.

background_color

The background_color field in the PWA manifest describes the expected background color of the web application. While this information is already available in the application stylesheet, the background_color field can be used by the user agent to draw the background color of a web application for which the manifest is known, even before the application’s files are fully loaded from the network or retrieved from disk.

The purpose of the background_color field is to enhance the user experience during the loading process of the web application. It allows the user agent to present a consistent background color while the application’s content is being loaded, creating a smoother visual transition for users. It’s important to note that once the web application’s stylesheet becomes available, the user agent must not use the background_color field as the background color anymore.

Implementors have the option to override the value defined by the background_color field to support the prefers-color-scheme feature, which enables adaptive theming based on the user’s preferred color scheme.

shortcuts

The shortcuts field in the PWA manifest is a list of shortcut items that offer quick access to key tasks within a web application.

The presentation and number of shortcuts shown to the user are determined by the user agent and/or operating system, as it is within their discretion.

To process the shortcuts field, the following steps are taken using the ordered maps json and manifest, as well as the URL manifest URL:

• Create a new list called processedShortcuts.
• Set the value of manifest[‘shortcuts’] to the processedShortcuts list.
• If json[‘shortcuts’] does not exist or is not a list, stop processing.
• For each entry in json[‘shortcuts’]:
  • Process the shortcut using the entry and manifest[‘scope’] and assign it to the variable shortcut.
  • If processing the shortcut fails, continue to the next entry.
  • Append the shortcut to the processedShortcuts list.

A user agent should expose shortcuts through interactions that are consistent with the application icon’s context menu in the host operating system, such as right-clicking or long-pressing. The user agent should render the shortcuts in the same order as provided in the manifest and represent them in a manner consistent with the application icon’s context menu in the host operating system. The user agent may truncate the list of shortcuts presented to align with the conventions or limitations of the host operating system.

Extended Fields of the PWA Manifest

The following set of fields provides optional additional information about your Progressive Web App (PWA). While not required, they offer valuable details and enhancements to your PWA:

lang

The lang field in the PWA manifest is a string in the form of a language tag. This language tag specifies the primary language for the values of the manifest’s localizable members. Additionally, knowing the language can assist with determining the directionality of the text.

A language tag follows the format defined in the [BCP47] specifications, which consists of one or more subtags separated by a hyphen-minus (“-“). These subtags represent specific language variations or regions. For example, the language tag en-AU represents English as spoken in Australia, while fr-CA represents French as spoken in Canada. Language tags that comply with the validity criteria outlined in [RFC5646] section 2.2.9 and can be verified without referencing the IANA Language Subtag Registry are considered structurally valid.

To process the lang field in the manifest, the following steps are taken using the ordered maps json and manifest:

• If the lang field does not exist or is not a string in json, stop processing.
• If the lang field in json is not a structurally valid language tag according to the IsStructurallyValidLanguageTag function, stop processing.
• Set the value of manifest[‘lang’] to the result of applying the CanonicalizeUnicodeLocaleId abstract operation to the value of json[‘lang’].

dir

The dir field in the PWA manifest specifies the base direction for the localizable members within the manifest. The dir field’s value can be set to one of the text-direction options.

The localizable members that are affected by the dir field are as follows:

• name member
• short_name member
• Name member of a shortcut item
• Short name member of a shortcut item
• Description member of a shortcut item

The available text-direction options are:

• ltr: Represents left-to-right text direction.
• rtl: Represents right-to-left text direction.
• auto (default): Indicates no explicit directionality.

When displaying the localizable members to an end-user, the user agent should follow the following guidelines:

• If the base direction is set to ltr or rtl, the user agent should override Rule P3 of [BIDI] and set the paragraph embedding level to 0 if the base direction is ltr, or 1 if the base direction is rtl.
• If the base direction is auto, the user agent should determine the text’s direction by applying Rule P1 of [BIDI].

To process the dir field in the manifest, the following steps are taken using the ordered maps json and manifest:

• Set the value of manifest[‘dir’] to auto as the default.
• If the dir field does not exist in json or is not a string, stop processing.
• If the dir field in json is not one of the valid text-direction options, stop processing.
• Set the value of manifest[‘dir’] to the value specified in json[‘dir’].

Promotional Fields of the PWA Manifest

The next set of fields allows you to provide promotional information about your Progressive Web App (PWA). This information serves to showcase your PWA in install flows, listings, and search results, helping to attract users and highlight its unique features.

description

The description field in the shortcut item of the PWA manifest is a string that allows developers to provide a description of the shortcut’s purpose. This description serves to explain the functionality or intent of the shortcut item. User agents have the option to expose this information to assistive technology, providing additional context and assistance to users with disabilities.

screenshots

The screenshots field in the PWA manifest is an array of screenshot objects. Each screenshot object contains the following properties: src, type, and sizes. These properties are similar to the icons object and are used to showcase the visual representation of the PWA.

The src property specifies the source URL or path of the screenshot image. It represents the location of the image file that showcases the PWA.

The type property denotes the file type or format of the screenshot image, such as image/png or image/jpeg. This information helps user agents and platforms understand the image format for proper rendering.

The sizes property provides additional information about the dimensions or size of the screenshot. This can be expressed in various formats, such as width x height or other size indicators. There are no specific size restrictions, allowing developers to include screenshots of any dimensions.

categories

The categories field in the PWA manifest is an array of categories to which the PWA belongs. These categories serve as hints for listings, providing guidance and context to platforms, app stores, or search results. The values in the categories array are typically lowercase.

Developers can choose categories that best represent the nature and purpose of their PWA. While optional, including relevant categories can assist in improving the discoverability and visibility of the PWA within relevant listings or search results.

When specifying the categories field, it’s recommended to use lowercase values for consistency and compatibility. This ensures compatibility with various platforms and search algorithms, providing a seamless and cohesive experience for users seeking applications in specific categories.

iarc_rating_id

This field in the PWA manifest represents the certification code from the International Age Rating Coalition (IARC) for your Progressive Web App (PWA), if applicable. This code is used to determine the appropriate age group for which your PWA is suitable.

The IARC certification code provides valuable information about the content and age appropriateness of your PWA. It helps platforms, app stores, or parental control settings determine the target audience and apply appropriate age restrictions or filters.

If you have obtained an IARC certification code for your PWA, it’s recommended to include it in the manifest. This demonstrates your commitment to providing a safe and age-appropriate experience for users and aligns your PWA with relevant age-rating guidelines and regulations.

External Application Resource of the PWA Manifest

Each external application resource within the context of the web application represents a related application that is associated with the web application.

An external application resource can consist of several members, some of which are required to form a valid external application resource:

platform

The platform member in the external application resource represents the specific platform to which the resource is associated. A platform refers to a software distribution ecosystem or potentially an operating system. This specification does not provide a specific list of values for the platform member.

url 

The url member in an external application resource represents the URL where the related application can be accessed.

To process the url member of an application, follow these steps:

• If the application URL is missing or not provided, return null.
• Otherwise, parse the application URL. If the parsing operation is successful and returns a valid result, return that result. If the parsing operation fails, return null.

id

The id member in an external application resource represents the unique identifier used to represent the application on the platform.

The id serves as a distinct value that uniquely identifies the application within the platform’s ecosystem. It enables efficient referencing and identification of the application, ensuring proper integration and interaction with the platform’s functionalities.

min_version

The min_version member in an external application resource represents the minimum version of the related application that is considered relevant to this web application. This version is specified as a string and follows platform-specific syntax and semantics.

The min_version serves as a criterion to establish compatibility and ensure that the related application meets the required version specifications. It allows the web application to communicate its compatibility requirements to the platform and users, ensuring optimal functionality and a seamless user experience.

fingerprints 

The fingerprints member in an external application resource represents a list of fingerprints.

A fingerprint in this context refers to a collection of cryptographic fingerprints that are utilized for verifying the authenticity and integrity of the application. Each fingerprint consists of two members: type and value. Both members are strings, but their specific syntax and semantics are defined by the platform.

The type member specifies the type of cryptographic fingerprint being used, such as SHA-1, SHA-256, or other platform-specific algorithms. It identifies the hashing algorithm employed to generate the fingerprint.

The value member contains the actual value of the cryptographic fingerprint. This value is derived from the application’s digital signature or other cryptographic processes, ensuring that it remains unique and tamper-resistant.

In Conclusion,

The PWA manifest plays a vital role in enhancing the functionality, discoverability, and user experience of your Progressive Web App (PWA).  By including a well-defined manifest file, developers can specify important details like the PWA’s name, icons, theme colors, start URL, display mode, and more. This enables browsers and platforms to recognize and treat the PWA as a standalone application, allowing for features such as installation, offline access, and integration with device capabilities.

However, configuring the PWA manifest is not a straightforward task and you always need help from experienced developers. Fortunately, at Magenest, we have a high-skilled and professional team of developers with our elite Magento PWA development service. Don’t be afraid to reach out to us to receive comprehensive consultancy!