Web App Manifest

Taking some notes on web app manifest because I finally want to implement notifications for this site.

Date Created:

Last Edited:

References

Progressive Web App
- A progressive web app (PWA) is an app that's built using web platform technologies, but that provides a user experience like that of a platform-specific app. Like a website, a PWA can run on multiple platforms and devices from a single codebase. Like a platform specific app, it can be installed on the device, can operate while offline and in the background, and can integrate with the device and other installed apps.
- Progressive Web App Reference

Notes

A web application manifest, defined in the Web Application Manifest specification, is a JSON text file that provides information about a web application.
The most common use for a web application manifest is to provide information that the browser needs to install a progressive web app (PWA) on a device, such as the app's name and icon.
A web application manifest contains a single JSON object where the top-level keys are called members.

Members

All members are optional, but some applications require some members to be present:

background_color

- The background_color manifest member is used to specify an initial background color for your web application. This color appears in the application window before your application's stylesheets have loaded.
- It provides a smooth visual transition from the app's initial launch to its fully loaded state.
- It improves user experience while the app files are loading over the network or being accessed form storage media.
- Contributes to the appearance of the splash screen in some browsers and operating systems when an installed progressive web app (PWA) is launched.
- It is recommended that the value matches the background-color of the application stylesheet.

/* Using named color */
"background_color": "aliceblue"
/* Using hexadecimal value */
"background_color": "#f0fbff"
/* Using RGB value */
"background_color": "rgb(240 248 255)"

categories

- Lets you specify one or more classifications for your web application. These categories help users discover your app in app stores.
- This member's values are used only in app stores and other distribution platforms and are not visible to users in the browser or installed app.
- If your app serves multiple purposes, specifying multiple relevant categories can help users discover your app across different sections of the app store. If you don't provide a value, app stores will use their own categorization system to categorize the app.

/* Single category */
"categories": ["productivity"]

/* Multiple categories */
"categories": ["productivity", "utilities", "social"]

description

- The description manifest member is used to explain the core features or functionality of your web application. This text helps users understand your app's purpose when viewing it in an app store.
- It's value is used in app stores and other distribution platforms to help users understand what your app does.

"description": "Track your daily tasks and plan your projects efficiently."

display

- Required by PWA

- Used to specify your preferred display mode for the web application. The display mode determines how much of the browser UI is shown to the user when the app is launched within the context of an operating system.
- display values
- - fullscreen
  - - The browser UI elements are hidden and the app uses the entirety of the display area. Use this when Fullscreen engagement is crucial and desired.
  - standalone
  - - Opens the app to look and feel like a standalone native app. This can include the app having a different window and its own app icon in the app launcher.
  - minimal-ui
  - - Opens the app to look and feel like a standalone app but with a minimal set of UI elements for navigation.
  - browser
  - - Opens the app in a conventional browser or new window, using the platform-specific convention for opening links.

/* Keyword values */
"display": "fullscreen"
"display": "standalone"
"display": "minimal-ui"
"display": "browser"

display_override

- The display_override member is the fallback for the display method if the requested display mode if not supported.
- This method includes all values available for display and:
- - tabbed
  - - The application can contain multiple application contexts inside a single OS-level window.
  - window-controls-overlay
  - - This display mode only applies when the application is in a separate PWA window and on a desktop operating system.

{
  "display_override": ["fullscreen", "minimal-ui"],
  "display": "standalone"
}

file_handlers

- The file_handlers member specifies an array of objects representing the types of files an installed PWA can handle. It is used when the PWA is installed to associate the application with a given set of files at the operating system level. For example, a PWA can be registered to handle files that match the text/plain MIME type.
- Each object in the array must contain the following values:
- - action
  - - String containing the URL to navigate to when a file is handled. This URL must be within the navigation scope of the PWA, which is the set of URLs that the PWA can navigate to. The navigation of a PWA defaults to its start_url member.
  - accept
  - - An object. For each property in the object:
    - - The property key is a MIME type.
      - The property value is an array of strings representing file extensions associated with that MIME type.

{
  "file_handlers": [
    {
      "action": "/handle-audio-file",
      "accept": {
        "audio/wav": [".wav"],
        "audio/x-wav": [".wav"],
        "audio/mpeg": [".mp3"],
        "audio/mp4": [".mp4"],
        "audio/aac": [".adts"],
        "audio/ogg": [".ogg"],
        "application/ogg": [".ogg"],
        "audio/webm": [".webm"],
        "audio/flac": [".flac"],
        "audio/mid": [".rmi", ".mid"]
      }
    }
  ]
}

- To actually implement file handling in a PWA, web developers also need to use window.launchQueue to handle the incoming files in their application JavaScript code. This is done in the main thread.

async function playSong(handledFile) {
  const blob = await handledFile.getFile();
  const url = window.URL.createObjectURL(blob);
  const audio = new Audio(url);
  audio.play();
}

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.files && launchParams.files.length) {
      playSong(launchParams.files[0]);
    }
  });
}

icons

- Required by PWA

- This manifest member is used to specify one or more image files that define the icons to represent your web application.

/* Single icon with the minimum required property */
"icons": [
  {
    "src": "icon/basic-icon.png"
  }
]

/* Single icon with multiple purposes */
"icons": [
  {
    "src": "icon/basic-icon.png",
    "purpose": "monochrome maskable"
  }
]

/* Two icons with various properties */
"icons": [
  {
    "src": "icon/low-res.png",
    "sizes": "48x48"
  },
  {
    "src": "maskable_icon.png",
    "sizes": "48x48",
    "type": "image/png"
  }
]

- icons
- - An array of objects. Each object represents an icon to be used in a specific context. For example, you can add icons to represent your web app on devices with different screen sizes, for integration with various operating systems, for splash screens, or for app notifications.
  - Each icon can have one or more properties, only src is required:
  - - src
    - - A string that specifies the path to the icon file/
    - sizes
    - - A string that specifies one or more sizes at which the icon file can be used. Specified as <width>x<height>. If multiple sizes are specified, separate them by a space: 48x48 96x96

- - - type
    - - A string that specifies the MIME type of the icon. The value should be in the format image/<subtype>, where <subtype> is the specific image format.
    - purpose
    - - A case sensitive keyword string that specifies one or more contexts in which the icon can be used by thr browser or operating system. Browsers use these values to determine where and how an icon is displayed. Values:
      - monochrome: Indicates that the icon is intended to be used as a monochrome icon with a solid fill.
      - maskable: Indicates that the icon is designed with icon masks and safe zone in mind, such that any part of the image outside the safe zone can be ignored and masked away.
      - any: Indicates that the icon can be used in any context.
- The img-src content security policy directive affects the manifest file.
- Specifying the type property can improve performance significantly.
id

- The id manifest member is used to specify a unique identifier for your web application. The URL must be same-origin with the start_url of your web app. If id is a relative URL, it is resolved using the origin of start_url

/* Absolute URL */
"id": "https://example.com/myapp"

/* Relative URL */
"id": "myapp/v2"

/* URL with query parameters */
"id": "myapp?version=2&mode=trial"

launch_handler

- Defines values that control the launch of a web application. Currently, it can only contain a single value, client_mode, which specifies the context in which the app should be loaded when launched.
- launch_handler objects may contain the following values:
- - client_mode
  - - A string, or comma-separated array of strings, which specifies the context in which the app should be loaded when launched. If an array of strings is provided, the first valid value is used.
    - auto
    - - The user agent decides what context makes sense for the platform to load the app in.
    - focus-existing
    - - If the app is already loaded in a web app client, it is brought into focus but not navigated to the launch target URL. The target URL is made available via Window.launchQueue to allow custom launch navigation handling to be implemented.
    - navigate-existing
    - - If the app is already loaded in a web app client, it is brought into focus and navigated to the specified launch target URL.
      - The target URL is made available via Window.launchQueue to allow custom launch navigation handling to be implemented.

- - - navigate-new
    - - The app is loaded inside a new web app client.
      - The target URL is made available via Window.launchQueue to allow custom launch navigation handling to be implemented.

"launch_handler": {
    "client_mode": "focus-existing"
}

"launch_handler": {
    "client_mode": ["focus-existing", "auto"]
}

name

- Required by PWA

- the name manifest member is used to specify the full name of your web application as it's usually displayed to users, such as in application lists or as for your application's icon.
- It serves as the accessible name for your installed app. It is displayed to users in various contexts, such as in a list of various installed webapps, as a label for your app's icon, or in the application switcher or task manager.

/* Full names of web apps */
"name": "Daily Task Planner"
"name": "Recipe and Pantry Tracker"

orientation

- The orientation manifest member is used to specify the default orientation for your web application. It defines how the app should be displayed when launched and during use, in relation to the device's screen orientation, particularly on devices that support multiple orientations.

/* Keyword values */
"orientation": "any"
"orientation": "natural"
"orientation": "portrait" // height greater than width. Seitchs from portraight-primary to portraight-secondary on device rotation
"orientation": "portrait-primary" 
"orientation": "portrait-secondary"
"orientation": "landscape"
"orientation": "landscape-primary"
"orientation": "landscape-secondary"

prefer_related_applications

- Required by PWA: must be false or not present
- Used to provide a hint to browsers whether to prefer installing native applications specified in the realted_applications manifest member over your web application.

/* Boolean values */
"prefer_related_applications": true
"prefer_related_applications": false

protocol_handlers

- Specifies an array of objects that are protocols which this web app can register and handle. Protocol handlers register the application in the OS's application preferences; the registration associates a specific application with the given protocol scheme.
- Protocol handler objects may contain the following values:
- - protocol
  - - A required string containing the protocol to be handled
  - url
  - - Required HTTPS URL within the application scope that will handle the protocol.

"protocol_handlers": [
  {
    "protocol": "web+jngl",
    "url": "/lookup?type=%s"
  },
  {
    "protocol": "web+jnglstore",
    "url": "/shop?for=%s"
  }
]

related_applications

- Used to specify one or more native applications that are related to your web application. It can be used with the prefer_related_applications manifest member, which indicates a preference for installing either a related native application or your web application.

/* Related native application on one platform specified by both url and id */
"related_applications": [
  {
    "platform": "play",
    "url": "https://play.google.com/store/apps/details?id=com.example.app1",
    "id": "com.example.app1"
  }
]

/* Related native application on one platform specified only by id */
"related_applications": [
  {
    "platform": "windows",
    "id": "example.app1"
  }
]

/* Related native applications on two platforms */
"related_applications": [
  {
    "platform": "play",
    "url": "https://play.google.com/store/apps/details?id=com.example.app1",
    "id": "com.example.app1"
  },
  {
    "platform": "amazon",
    "url": "https://www.amazon.com/product/dp/B000XA1000"
  }
]

scope

- Used to specify the top-level URL path that contains your web application's pages and subdirectories. When users install and use your web app, pages within scope provide an app-like interface.
- The scope member defines the URLs that are part of your web app's installed experience.

/* Absolute URL */
"scope": "https://example.com/myapp/"
/* Relative URL */
"scope": "/myapp/"
/* Scope limited to a specific directory */
"scope": "/myapp/dashboard/"

screenshots

- The screenshots manifest member lets you specify one or more images that showcase your web application. These images help users preview your web app's interface and features in app stores.
- screenshots Reference

/* Single screenshot */
"screenshots": [
  {
    "src": "desktop.webp",
    "sizes": "1280x720",
    "type": "image/webp"
  }
]

/* Two screenshots */
"screenshots": [
  {
    "src": "screenshots/home.webp",
    "sizes": "1280x720",
    "type": "image/webp",
    "form_factor": "wide",
    "label": "Home screen showing main navigation and featured content"
  },
  {
    "src": "screenshots/dashboard.webp",
    "sizes": "1280x720",
    "type": "image/webp",
    "platform": "ios",
    "label": "Dashboard view displaying key metrics"
  }
]

serviceworker

- This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web.
share_target
- The share_target manifest member allows installed PWAs to be registered as a share target in the system's share dialog. Once registered and installed, a PWA uses the Web Share Target API acts as a content sharing target, along with a typical share targets like email, messengers, and other native apps that can revive shared content.
- The value of the share_target member is an object that defines how an application can receive shared data. This object can obtain the following properties (action and params are required):
- - action: The URL for the web share target
  - enctype: The encoding of the share data when a POST request is used.
  - method: The HTTP request method to use. Either GET or POST. Use POST of the shared data includes binary data like image(s), or if it changes the target app.
  - params: An object to configure the share parameters
  - - title: Name of the query parameter to use for the title of the document being shared
    - text: Name of the query parameter for the text (or body) of the message being shared
    - url: Name of the query parameter for the URL to the resource being shared.
    - files:
    - - name: Name of the form field used to share files.
      - accept: A string (or an array of strings) of accepted MIME types or file extensions.

{
  "share_target": {
    "action": "/shared-content-receiver/",
    "method": "GET",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link"
    }
  }
}

short_name

- Required by PWA

- The short_name manifest member is used to specify a short name for your web application, which may be used when the full name is too long for the available space.

/* Short names of web apps */
"short_name": "TaskPlanner"
"short_name": "RecipePantry"

shortcuts

- The shortcuts manifest member is used to specify links to key tasks or pages within your web application. Browsers can use this information to create a context menu, which is typically displayed when a user interacts with the web app's icon.

/* Single shortcut with all properties */
"shortcuts": [
  {
    "name": "Today's agenda",
    "short_name": "Agenda",
    "description": "View your agenda for today",
    "url": "/today",
    "icons": [
      {
        "src": "today.png",
        "sizes": "192x192"
        }
    ]
  }
]

/* Two shortcuts with the required properties */
"shortcuts": [
  {
    "name": "Today's agenda",
    "url": "/today"
  },
  {
    "name": "Tomorrow's agenda",
    "url": "/tomorrow"
  }
]

/* Shortcut with a relative URL */
"shortcuts": [
  {
    "name": "This week's agenda",
    "url": "../agenda"
  }
]

- An array of objects. Each object represents a key task in the web app. Of these, only name and url are required.
- - name
  - - A string that represents the name of the shortcut, which is displayed to users in a context menu.
  - short_name
  - - A string that represents a short version of the shortcut's name.
  - description
  - - A string that describes the purpose of the shortcut. Browsers may expose this information to assistive technology, such as screen readers, which can help users understand the purpose of the shortcut.
  - url
  - - An app URL that opens when the associated shortcut is activated. The URL must be within the scope of the web app manifest.
  - icons
  - - An array of icon objects representing the shortcut in various contexts.
start_url

- Required by PWA

- The start_url manifest member is used to specify the URL that should be opened when a user launches your web application, such as when tapping the application's icon on their device's home screen or in an application list.

/* Absolute URLs */
"start_url": "https://example.com/myapp"
"start_url": "https://myapp.com/home"

/* Relative URLs */
"start_url": "/"
"start_url": "../index.html"

theme_color
- The theme_color member is used to specify the default color for your web application's user interface. This color may be applied to various browser UI elements, such as the toolbar, address bar, and status bar.

/* Valid named color */
"theme_color": "rebeccapurple"

/* Using hexadecimal value */
"theme_color": "#42b5f4"

/* Using RGB value */
"theme_color": "rgb(66 133 244)"

Example Manifest

{
  "short_name": "MDN",
  "name": "MDN Web Docs",
  "icons": [
    {
      "src": "/favicon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/favicon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff"
}

Deploying a Manifest

<link rel="manifest" href="manifest.json" />
<!-- If the manifest requires credentials to fetch, the crossorigin attribute must be set to use-credentials, even if the manifest file is in the same origin as the current page -->

Web App Manifest

References

Related

Notes

Members

Example Manifest

Deploying a Manifest

Comments

Inserting Custom HTML:

Basics:

Inserting Code Expressions:

Inserting $\Large{LaTeX}$ Expressions:

SVG Icon Search

AI Code Generation

The Sanitization of HTML