Web Application Manifest Specification

A Web Application Manifest is a separate JSON file used to provide metadata about a web application. Using a dedicated file instead of HTML <meta> tags offers two primary advantages:

1. Performance: It avoids loading heavy header information on every single page of an installable app/site.
2. Caching: Once downloaded, the manifest file is stored in the browser's HTTP cache, making it available for subsequent use without repeated network requests.

Start URL

The start_url property specifies the exact page the application should load first when the user launches it from their homescreen.

Scope

The scope property defines the URL boundary of your application. It can be a domain or a specific directory. This helps the browser understand which URLs belong to the app and prevents the user from accidentally navigating out of the app's context into a different origin.

{
 "start_url": "/start_screen.html",
 "scope": "/myapp"
}

The manifest uses two primary members to define the application's identity:

• name: The full, descriptive name of the application. This is used in contexts where space is available and can be used by users to search for the app on their device.
• short_name: A condensed version of the name used when space is constrained, such as under an icon on a mobile homescreen.

If these are omitted, browsers may fall back to <meta name="application-name"> or the document's <title> element. Note that omitting names may prevent your app from being recognized as a valid Progressive Web App.

{
  "name": "My totally awesome photo app",
  "short_name": "Photos"
}

To allow a browser to treat your website as an installable application (a Progressive Web App), you must link a JSON manifest file within your HTML document using a <link> tag with rel="manifest".

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

Web application manifests should be accessible to browsers and crawlers. If you want to prevent web crawlers from indexing your manifest file, you have two primary options:

1. robots.txt: Include the manifest file path in your robots.txt file following the robots.txt protocol.
2. HTTP Headers: Use the X-Robots-Tag HTTP header to instruct crawlers.

You can listen for the appinstalled event to trigger logic when a user successfully installs your web application. Note that for privacy reasons, you can only detect if the manifest is being used with your application, not whether the app is currently installed on the device.

function handleInstalled(ev) {
  const date = new Date(ev.timeStamp / 1000);
  console.log(`Yay! Our app got installed at ${date.toTimeString()}`);
}

// Using .addEventListener()
window.addEventListener("appinstalled", handleInstalled);

The Web Application Manifest and Progressive Web App (PWA) standards are currently implemented in:

• Chrome
• Opera
• Samsung Internet (for Android)

Note: While the implementation exists in Gecko (Firefox), it may not be enabled in all Firefox products yet.

The shortcuts array allows you to define quick-access menu items that appear when a user interacts with the app icon (e.g., via long-press or right-click). Each shortcut object requires a name and a url, and can optionally include a description and icons.

"shortcuts": [
  {
    "name": "Play Later",
    "description": "View the list of podcasts you saved for later",
    "url": "/play-later",
    "icons": [
      {
        "src": "/icons/play-later.svg",
        "type": "image/svg+xml",
        "purpose": "any"
      }
    ]
  }
]

The icons property accepts a list of icon objects to provide a responsive image solution for different device densities and screen sizes. Each object can include:

• src: The path to the icon image.
• sizes: The dimensions (e.g., 64x64).
• type: The MIME type (e.g., image/webp).

If no icons are provided in the manifest, the browser may fall back to the <link rel="icon"> (favicon), or a screenshot of the website.

{
  "icons": [{
    "src": "icon/lowres",
    "sizes": "64x64",
    "type": "image/webp"
  }, {
    "src": "icon/hd_small",
    "sizes": "64x64"
  }, {
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }]
}