Web App Manifest

W3C Working Draft

This version:
https://www.w3.org/TR/2020/WD-appmanifest-20200319/
Latest published version:
https://www.w3.org/TR/appmanifest/
Latest editor's draft:
https://w3c.github.io/manifest/
Previous version:
https://www.w3.org/TR/2020/WD-appmanifest-20200318/
Editors:
Marcos Caceres (Mozilla Corporation)
Kenneth Rohde Christiansen (Intel Corporation)
Mounir Lamouri (Google Inc.)
Anssi Kostiainen (Intel Corporation)
Matt Giuca (Google Inc.)
Aaron Gustafson (Microsoft Corporation)
Former editor:
Rob Dolin (Microsoft Corporation)
Participate:
GitHub w3c/manifest
File a bug
Commit history
Pull requests
Implementation status:
Blink
EdgeHTML
Gecko
WebKit
Browser support:
caniuse.com

Abstract

This specification defines a JSON-based manifest file that provides developers with a centralized place to put metadata associated with a web application. This metadata includes, but is not limited to, the web application's name, links to icons, as well as the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to "scope" a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to "deep link" into a web application from other applications.

Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.

This specification also defines the manifest link type as a declarative means to associate a document with a manifest.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Warning

Implementors need to be aware that this specification is not stable. However, aspects of this specification are shipping in at least one browser (see links to implementation status at the top of this document). Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Usage Examples

This section is non-normative.

This section shows how developers can make use of the various features of this specification.

1.1 Example manifests

This section is non-normative.

The following shows a very simple manifest.

Example 1: very simple manifest
{
  "name": "Donate App",
  "description": "This app helps you donate to worthy causes.",
  "icons": [{
    "src": "images/icon.png",
    "sizes": "192x192"
  }]
}

The following shows a more typical manifest.

Example 2: typical manifest
{
  "lang": "en",
  "dir": "ltr",
  "name": "Super Racer 3000",
  "description": "The ultimate futuristic racing game from the future!",
  "short_name": "Racer3K",
  "icons": [{
    "src": "icon/lowres.webp",
    "sizes": "64x64",
    "type": "image/webp"
  },{
    "src": "icon/lowres.png",
    "sizes": "64x64"
  }, {
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }],
  "scope": "/racer/",
  "start_url": "/racer/start.html",
  "display": "fullscreen",
  "orientation": "landscape",
  "theme_color": "aliceblue",
  "background_color": "red",
  "screenshots": [{
    "src": "screenshots/in-game-1x.jpg",
    "sizes": "640x480",
    "type": "image/jpeg"
  },{
    "src": "screenshots/in-game-2x.jpg",
    "sizes": "1280x920",
    "type": "image/jpeg"
  }]
}

2. Installable web applications

A common use case of a manifest is for a user agent to install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. That is, the manifest's members, or their defaults, are in effect on the top-level browsing context. This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.

For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When launched, the manifest is applied by the user agent to the top-level browsing context prior to the start URL being loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.

A Document may either be installable or not. The initial state of a document is not installable.

At any time, the user agent MAY perform the steps to determine installability of the document:

  1. Let manifest and manifest URL be the result of obtaining the manifest.
  2. If obtaining the manifest results in an error, the user agent MAY either:
    1. Fall back to using the top-level browsing context Document's metadata to to populate manifest in a user-agent-specific way (e.g., setting manifest.name to the document title) and considering the document installable.
    2. Or, consider the document not installable.
  3. Otherwise, the Document MAY be considered installable (at the user agent's discretion; see § 2.6 Installability signals ).

2.1 Authority of the manifest's metadata

When a manifest is linked from a Document, it indicates to the user agent that the metadata is authoritative: that is, the user agent SHOULD use the metadata of the manifest instead of the one in the Document. However, in cases where metadata is missing, or in error, a user agent MAY fallback to the Document to find suitable replacements for missing manifest members (e.g., using application-name in place of short_name).

2.2 Application's name

The application's name is derived from either the name member or short_name member (if either is present) - otherwise, it is generated by the user agent or provided by the end-user.

When either member is missing from the manifest, a user agent MAY use the name member as a fallback for the short_name member or vice versa.

If the name and short_name members are undefined, the user agent SHOULD assign a default name (e.g., "Untitled") that follows platform conventions. Alternatively, a user agent MAY allow the end-user to input some text that can serve as the application's name.

When both the name and short_name members are present, it is left up to implementations to decide which member is best suited for the space available (e.g., the short_name member might be better suited for the space available underneath an icon).

2.3 Installation process

The steps to install the web application are given by the following algorithm:

  1. Let manifest be the manifest value created during steps to determine installability of the document.
  2. Perform an unspecified sequence of actions to attempt to register the web application in the user's operating system (e.g., create shortcuts that launch the web application, register the application in the system uninstall menu, etc.). If the installation fails (which can be for any reason, for example, the OS denying permission to the user agent to add an icon to the home screen of the device), abort these steps.
  3. Queue a task on the application life-cycle task source to fire an event named appinstalled at the the Window object of the top-level browsing context for which the installation took place.

2.4 Install prompts

There are multiple ways that the installation process can be triggered:

In any case, the user agent MUST NOT present an install prompt if the document is not installable.

Prior to presenting an automated install prompt, a user agent MUST run the steps to notify that an install prompt is available, to give the site the opportunity to prevent the default action (which is to install the application). Alternatively, the user agent MAY, at any time (only if the document is installable), run the steps to notify that an install prompt is available at any time, giving the site the opportunity to show a site-triggered install prompt without automatically showing the prompt.

To present an install prompt:

  1. Show some user-agent-specific UI, asking the user whether to proceed with installing the app. See privacy and security considerations for recommendations relating to this UI. The result of this choice is either accepted or dismissed.
  2. Return result, and in parallel:
    1. If result is accepted, run the steps to install the web application.

The steps to notify that an install prompt is available are given by the following algorithm:

  1. Wait until the Document of the top-level browsing context is completely loaded.
  2. If there is already an install prompt being presented or if the steps to install the web application are currently being executed, then abort this step.
  3. Queue a task on the application life-cycle task source to do the following:
    1. Let event be a newly constructed BeforeInstallPromptEvent named beforeinstallprompt, with its cancelable attribute initialized to true.
    2. Let mayShowPrompt be the result of firing event at the Window object of the top-level browsing context.
    3. If mayShowPrompt is true, then the user agent MAY, in parallel, request to present an install prompt with event.

2.5 Privacy and security considerations

During the presentation of the install prompt, it is RECOMMENDED that the user agent allow the end-user to inspect the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.

It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.

2.6 Installability signals

This section is non-normative.

By design, this specification does not provide developers with an explicit API to "install" a web application. Instead, a manifest can serve as an installability signal to a user agent that a web application can be installed.

Examples of installability signals for a web application:

This list is not exhaustive and some installability signals might not apply to all user agents. How a user agent makes use of these installability signals to determine if a web application can be installed is left to implementers.

2.7 Uninstallation

User agents SHOULD provide a mechanism for the user to remove the installed application.

It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.

3. Installation Events

Installation events and supporting the BeforeInstallPrompt is OPTIONAL.

DOM events fired by this specification use the application life-cycle task source.

3.1 BeforeInstallPromptEvent Interface

Note
The beforeinstallprompt event is somewhat misnamed, as it does not necessarily signal that an automated install prompt will follow (depending on the user agent, it might just be giving the site the ability to trigger an install prompt). It is so named for historical reasons.
WebIDL[Exposed=Window]
interface BeforeInstallPromptEvent : Event {
  constructor(DOMString type, optional EventInit eventInitDict = {});
  Promise<PromptResponseObject> prompt();
};

dictionary PromptResponseObject {
  AppBannerPromptOutcome userChoice;
};

enum AppBannerPromptOutcome {
  "accepted",
  "dismissed"
};

The BeforeInstallPromptEvent is dispatched when the site is allowed to present a site-triggered install prompt, or prior to the user agent presenting an automated install prompt. It allows the site to cancel the automated install prompt, as well as manually present the site-triggered install prompt.

Note
If the BeforeInstallPromptEvent is not cancelled, the user agent is allowed to present an install prompt (specifically, an automated install prompt) to the end-user. Canceling the default action (via preventDefault) prevents the user agent from presenting an install prompt. The user agent is free to run steps to notify that an install prompt is available again at a later time.

The PromptResponseObject contains the result of calling prompt(). It contains one member, userChoice, which states the user's chosen outcome.

An instance of a BeforeInstallPromptEvent has the following internal slots:

[[didPrompt]]
A boolean, initially false. Represents whether this event was used to present an install prompt to the end-user.
[[userResponsePromise]]
A promise that represents the outcome of presenting an install prompt.

3.1.1 prompt() method

The prompt method, when called, runs the following steps:

  1. If this.[[userResponsePromise]] is pending:
    1. If this event's isTrusted attribute is false, reject this.[[userResponsePromise]] with "NotAllowedError", optionally informing the developer that untrusted events can't call prompt().
    2. Else if this.[[didPrompt]] is false, set this.[[didPrompt]] to true, then in parallel, request to present an install prompt with this event. Wait, possibly indefinitely, for the end-user to make a choice.
  2. Return this.[[userResponsePromise]].

To request to present an install prompt with BeforeInstallPromptEvent event:

  1. Present an install prompt and let outcome be the result.
  2. Resolve event.[[userResponsePromise]] with a newly created PromptResponseObject whose userChoice member is the value of outcome.

3.1.2 Usage example

This section is non-normative.

This example shows how one might prevent an automated install prompt from showing until the user clicks a button to show a site-triggered install prompt. In this way, the site can leave installation at the user's discretion (rather than prompting at an arbitrary time), whilst still providing a prominent UI to do so.

Example 4: Using beforeinstallprompt to present an install button
window.addEventListener("beforeinstallprompt", event => {
  // Suppress automatic prompting.
  event.preventDefault();

  // Show the (disabled-by-default) install button. This button
  // resolves the installButtonClicked promise when clicked.
  installButton.disabled = false;

  // Wait for the user to click the button.
  installButton.addEventListener("click", async e => {
    // The prompt() method can only be used once.
    installButton.disabled = true;

    // Show the prompt.
    const { userChoice } = await event.prompt();
    console.info(`user choice was: ${userChoice}`);
  });
});

3.1.3 AppBannerPromptOutcome enum

The AppBannerPromptOutcome enum's values represent the outcomes from presenting an install prompt.

accepted:
The end-user indicated that they would like the user agent to install the web application.
dismissed:
The end-user dismissed the install prompt.

3.2 Extensions to the Window object

The following extensions to the Window object specify the event handler idl attribute on which events relating to the installation of a web application are fired.

WebIDLpartial interface Window {
  attribute EventHandler onappinstalled;
  attribute EventHandler onbeforeinstallprompt;
};
Example 5: Two ways of handling the 'appinstalled' event
function handleInstalled(ev) {
  const date = new Date(ev.timeStamp / 1000);
  console.log(`Yay! Our app got installed at ${date.toTimeString()}.`);
}

// Using the event handler IDL attribute
window.onappinstalled = handleInstalled;

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

3.2.1 onappinstalled attribute

The onappinstalled is an event handler IDL attribute for the "appinstalled" event type. The interface used for these events is the Event interface [DOM]. This event is dispatched as a result of a successful installation (see the steps to install the web application).

3.2.2 onbeforeinstallprompt attribute

The onbeforeinstallprompt is an event handler IDL attribute for the "beforeinstallprompt" event type. The interface used for these events is the BeforeInstallPromptEvent interface (see the steps to notify that an install prompt is available).

5. Display modes

A display mode represents how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.). Display modes correspond to user interface (UI) metaphors and functionality in use on a given platform. The UI conventions of the display modes are purely advisory and implementers are free to interpret them how they best see fit.

Once a user agent applies a particular display mode to an application context, it becomes the default display mode for the top-level browsing context (i.e., it is used as the display mode when the window is navigated). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode.

When the display member is missing, or if there is no valid display member, the user agent uses the browser display mode as the default display mode. As such, the user agent MUST support the browser display mode.

Each display mode, except browser, has a fallback display mode, which is the display mode that the user agent can try to use if it doesn't support a particular display mode. If the user agent does support a fallback display mode, then it checks to see if it can use that display mode's fallback display mode. This creates a fallback chain, with the default display mode (browser) being the last item in the chain.

For example, SuperSecure Browser (a fictitious browser) only supports the minimal-ui and browser display modes, but a developer declares that she wants fullscreen in the manifest. In this case, the user agent will first check if it supports fullscreen (it doesn't), so it falls back to standalone (which it also doesn't support), and ultimately falls back to minimal-ui.

The display modes values defined by DisplayModeType, and their corresponding fallback display modes are as follows:

fullscreen
Opens the web application without any user agent chrome and takes up the entirety of the available display area.
The fallback display mode for fullscreen is standalone.
standalone
Opens the web application to look and feel like a standalone native application. This can include the application having a different window, its own icon in the application launcher, etc. In this mode, the user agent will exclude standard browser UI elements such as an URL bar, but can include other system UI elements such as a status bar and/or system back button.
The fallback display mode for standalone is minimal-ui.
minimal-ui
This mode is similar to standalone, but provides the end-user with some means to access a minimal set of UI elements for controlling navigation (i.e., back, forward, reload, and perhaps some way of viewing the document's address). A user agent can include other platform specific UI elements, such as "share" and "print" buttons or whatever is customary on the platform and user agent.
The fallback display mode for minimal-ui is browser.
browser
Opens the web application using the platform-specific convention for opening hyperlinks in the user agent (e.g., in a browser tab or a new window).
The browser display mode doesn't have a fallback display mode (conforming user agents are required to support the browser display mode).
Note

The fullscreen display mode is orthogonal to, and works independently of, the Fullscreen API Standard. The fullscreen display mode affects the fullscreen state of the browser window, while the [FULLSCREEN] API operates on an element contained within the viewport. As such, a web application can have its display mode set to fullscreen, while document.fullScreenElement returns null, and fullscreenEnabled returns false.

5.1 Privacy and security considerations

When the web application is running, it is RECOMMENDED that the user agent provides the end-user a means to access common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.

Additionally, when applying a manifest that sets the display mode to anything except "browser", it is RECOMMENDED that the user agent clearly indicate to the end-user that their are leaving the normal browsing context of a web browser. Ideally, launching or switching to a web application is performed in a manner that is consistent with launching or switching to other applications in the host platform. For example, a long and obvious animated transition, or speaking the text "Launching application X".

5.2 The 'display-mode' media feature

The display-mode media feature represents, via a CSS media query [MEDIAQ], the display mode of the web application. This media feature applies to the top-level browsing context and any child browsing contexts. Child browsing contexts reflect the display mode of the top-level browsing context.

A user agent MUST expose the 'display-mode' media feature irrespective of whether a manifest is being applied to a browsing context. For example, if the end-user puts the whole user agent into fullscreen, then the user agent would reflect this change to CSS and scripts via the 'display-mode' media feature.

Note

Please note that the fullscreen display mode is not directly related to the CSS :fullscreen pseudo-class specified in the Fullscreen API Standard. The :fullscreen pseudo-class matches exclusively when a [HTML] element is put into the fullscreen element stack. However, a side effect of calling the requestFullscreen() method on an element using the [FULLSCREEN] API is that the browser window can enter a fullscreen mode at the OS-level. In such a case, both :fullscreen and (display-mode: fullscreen) will match.

On some platforms, it is possible for a user to put a browser window into fullscreen without the aid of the Fullscreen API Standard. When this happens, the :fullscreen pseudo class will not match, but (display-mode: fullscreen) will match. This is exemplified in CSS code below.

/* applies when the window is fullscreen */
@media all and (display-mode: fullscreen) {
    ...
}

/* applies when an element goes fullscreen */
#game:fullscreen {
    ...
}
Value:
fullscreen | standalone | minimal-ui | browser
Applies to:
visual media types
Accepts min/max prefixes:
No

A user agent MUST reflect the applied display mode of the web application via a CSS media query [MEDIAQ].

5.2.1 Examples

An example in CSS:

@media all and (display-mode: minimal-ui) {
  /* ... */
}
@media all and (display-mode: standalone) {
  /* ... */
}

Accessing the display-mode media feature in ECMAScript through matchMedia() of [CSSOM-VIEW]:

const standalone = matchMedia( '(display-mode: standalone)' );

standalone.onchange = (e) => {
  /* handle changes to display mode */
}

if (standalone.matches) {
  /* do standalone things */
}

5.2.2 Security and privacy considerations

The 'display-mode' media feature allows an origin access to aspects of a user’s local computing environment and, together with the display member, allows an origin some measure of control over a user agent’s native UI: Through a CSS media query, a script can know the display mode of a web application. An attacker could, in such a case, exploit the fact that an application is being displayed in fullscreen to mimic the user interface of another application.

6. Associating a resource with a manifest

A resource is said to be associated with a manifest if the resource representation, an HTML document, has a manifest link relationship.

6.1 Linking to a manifest

The manifest keyword can be used with a [HTML] link element. This keyword creates an external resource link.

Link type Effect on... Brief description
link a and area
manifest External Resource Link not allowed Imports or links to a manifest.

The MIME type for a manifest serves as the default MIME type for resources associated with the "manifest" link type.

Note

In cases where more than one link element with a manifest link type appears in a Document, the user agent uses the first link element in tree order and ignores all subsequent link elements with a manifest link type (even if the first element was erroneous). See the steps for obtaining a manifest.

To obtain a manifest, the user agent MUST run the steps for obtaining a manifest. The appropriate time to obtain the manifest is left up to implementations. A user agent MAY opt to delay fetching a manifest until after the document and its other resources have been fully loaded (i.e., to not delay the availability of content and scripts required by the document).

A manifest is obtained and applied regardless of the media attribute of the link element matches the environment or not.

7. Manifest life-cycle

This section defines algorithms for obtaining, processing, and applying a manifest.

7.1 Obtaining a manifest

The steps for obtaining a manifest are given by the following algorithm. The algorithm, if successful, returns a processed manifest and the manifest URL; otherwise, it aborts prematurely and returns nothing. In the case of nothing being returned, the user agent MUST ignore the manifest declaration. In running these steps, a user agent MUST NOT delay the load event.

  1. From the Document of the top-level browsing context, let origin be the Document's origin, and manifest link be the first link element in tree order whose rel attribute contains the token manifest.
  2. If origin is an opaque origin, then abort these steps.
  3. If manifest link is null, then abort these steps.
  4. If manifest link's href attribute's value is the empty string, then abort these steps.
  5. Let manifest URL be the result of parsing the value of the href attribute, relative to the element's base URL. If parsing fails, then abort these steps.
  6. Let request be a new Request.
  7. Set request's URL to manifest URL.
  8. Set request's initiator to "manifest".
  9. If the manifest link's crossOrigin attribute's value is "use-credentials", then set request's credentials mode to "include". Otherwise, set request's credentials mode to "omit".
  10. Set request's mode to "cors".
  11. Await the result of performing a fetch with request, letting response be the result.
  12. If response is a network error, then abort these steps.
  13. Let text be UTF-8 decode response's body.
  14. Let manifest be the result of running processing a manifest given text, manifest URL, and the URL that represents the address of the top-level browsing context.
  15. Return manifest and manifest URL.

7.1.1 Content security policy

A user agent MUST support [CSP3].

The manifest-src and default-src directives govern the origins from which a user agent can fetch a manifest. As with other directives, by default the manifest-src directive is *, meaning that a user agent can, [FETCH]'s CORS permitting, fetch the manifest cross-domain. Remote origins (e.g., a CDN) wanting to host manifests for various web applications will need to include the appropriate CORS response header in their HTTP response (e.g., Access-Control-Allow-Origin: https://example.com).

manifest-src directive example illustrated
Figure 1 For a [HTML] document, [CSP3]'s manifest-src directive controls the sources from which a [HTML] document can load a manifest from. The same CSP policy's img-src directive controls where the icon's images can be fetched from.

7.2 Processing the manifest

When instructed to issue a developer warning, the user agent MAY report the conformance violation to the developer in a user-agent-specific manner (e.g., report the problem in an error console), or MAY ignore the error and do nothing.

When instructed to ignore, the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.

The following algorithm provides an extension point: other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm. They SHOULD NOT modify the existing values already in the manifest object.

Note

The extension point is meant to help avoid issues related to monkey patching.

The steps for processing a manifest are given by the following algorithm. The algorithm takes a string text as an argument, which represents a manifest, and a URL manifest URL, which represents the location of the manifest, and a URL document URL. The output from inputting an JSON document into this algorithm is a processed manifest.

Issue

We need to catch throws associated with enumerations in IDL conversion as the spec might gain new values over time not supported by all exising browsers. This is especially important as we rely on enums not defined in this specification.

  1. Let json be the result of parsing text. If parsing throws an error:
    1. Issue a developer warning with any details pertaining to the JSON parsing error.
    2. Set json to be the result of parsing the string "{}".
  2. If Type(json) is not Object:
    1. Issue a developer warning that the manifest needs to be an object.
    2. Set json to be the result of parsing the string "{}".
  3. Let manifest be the result of converting json to a WebAppManifest dictionary.
  4. Set manifest["start_url"] to the result of running processing the start_url member given manifest["start_url"], manifest URL, and document URL.
  5. Set manifest["lang"] to the result of running processing the lang member given manifest["lang"].
  6. Set manifest["scope"] to the result of running processing the scope member given manifest["scope"], manifest URL, and manifest["start_url"].
  7. Set manifest["theme_color"] to the result of running processing the theme_color member given manifest["theme_color"].
  8. Set manifest["background_color"] to the result of running processing the background_color member given manifest["background_color"].
  9. Set manifest["categories"] to the result of running processing the categories member given manifest["categories"].
  10. Set manifest["icons"] to the result of running processing ImageResource members given manifest["icons"] and manifest URL.
  11. Set manifest["screenshots"] to the result of running processing ImageResource members given manifest["screenshots"] and manifest URL.
  12. Set manifest["related_applications"] to the result of running processing the related_applications member given manifest["related_applications"].
  13. Set manifest["shortcuts"] to the result of running processing the shortcuts member given manifest["shortcuts"] and manifest URL.
  14. Extension point: process any proprietary and/or other supported members at this point in the algorithm.
  15. Return manifest.

7.3 Applying the manifest

A manifest is applied to a top-level browsing context, meaning that the members of the manifest are affecting the presentation or behavior of a browsing context.

A top-level browsing context that has a manifest applied to it is referred to as an application context.

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent MUST immediately navigate to the deep link with replacement enabled. Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with replacement enabled.

Note

The start URL is not necessarily the value of the start_url member: the user or user agent could have changed it when the application was installed.

The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.

7.4 Updating the manifest

Issue 446: Support a way to update explicitly Feature Request

Is there a reason that the spec only defines a declarative way to request that a user agent obtain and process a manifest?

Likewise, it would be useful to have an explicit way to request that the user-agent update it's version of the manifest.

8. WebAppManifest dictionary

WebIDLdictionary WebAppManifest {
   TextDirectionType dir = "auto";
   DOMString lang;
   USVString name;
   USVString short_name;
   USVString description;
   sequence<ImageResource> icons;
   sequence<ImageResource> screenshots;
   sequence<USVString> categories;
   DOMString iarc_rating_id;
   USVString start_url;
   DisplayModeType display = "browser";
   OrientationLockType orientation;
   USVString theme_color;
   USVString background_color;
   USVString scope;
   sequence<ExternalApplicationResource> related_applications;
   boolean prefer_related_applications = "false";
   sequence<ShortcutItem> shortcuts;
};

A manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched.

Every manifest has an associated manifest URL, which is the [URL] from which the manifest was fetched.

8.1 dir member

WebIDLenum TextDirectionType { "ltr", "rtl", "auto" };

The dir member specifies the base direction for the directionality-capable members of the manifest. The dir member's value can be set to one of the text-direction values.

The directionality-capable members are:

The text-direction values defined by TextDirectionType, are the following, implying that the value of the directionality-capable members is by default:

ltr
Left-to-right text.
rtl
Right-to-left text.
auto
No explicit directionality.

When displaying the directionality-capable members to an end-user, if the base direction is ltr or rtl:

  1. If the member is being displayed in a paragraph by itself, the user agent MUST override Rule P3 of [BIDI], setting the paragraph embedding level to 0 if the base direction is ltr, or 1 if the base direction is rtl.
  2. Otherwise, the user agent MUST behave as if the member is in a left-to-right embedding [BIDI] if the base direction is ltr, or a right-to-left embedding if the base direction is rtl.

8.2 lang member

The lang member is a language tag (string) that specifies the primary language for the values of the manifest's directionality-capable members (as knowing the language can also help with directionality).

A language tag is a string that matches the production of a Language-Tag defined in the [BCP47] specifications (see the IANA Language Subtag Registry for an authoritative list of possible values). That is, a language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS ("-"). For example, the 'en-AU' language range represents English as spoken in Australia, and 'fr-CA' represents French as spoken in Canada. Language tags that meet the validity criteria of [RFC5646] section 2.2.9 that can be verified without reference to the IANA Language Subtag Registry are considered structurally valid.

The steps for processing the lang member is given by the following algorithm. The algorithm takes a WebAppManifest manifest as an argument. This algorithm returns a DOMString?.

  1. Let value be manifest["lang"].
  2. If Type(value) is String:
    1. If calling IsStructurallyValidLanguageTag with value as the argument returns false, then:
      1. Issue a developer warning that the value is invalid.
      2. Return undefined.
    2. Otherwise, return the result of calling the CanonicalizeLanguageTag abstract operation, passing V as the argument.
  3. Return undefined

8.3 name member

The name member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon).

8.4 short_name member

The short_name member is a string that represents a short version of the name of the web application. It is intended to be used where there is insufficient space to display the full name of the web application.

8.5 description member

The description member allows the developer to describe the purpose of the web application.

8.6 scope member

People are confused by the lack of examples relating to scope:
pwa-builder/PWABuilder-CLI#42 (comment)

The scope member is a string that represents the navigation scope of this web application's application context.

The steps for processing the scope member is given by the following algorithm. The algorithm takes a USVString value, a URL manifest URL, and a URL start URL. This algorithm returns a URL.

  1. Let default be the result of parsing ".", using start URL as the base URL.
  2. If value is the empty string, then return default.
  3. Let scope URL be the result of parsing value, using manifest URL as the base URL.
  4. If scope URL is failure:
  5. If start URL is not within scope of scope URL:
    1. Issue a developer warning that the start URL is not within scope of the scope URL.
    2. Return default.
  6. Otherwise, return scope URL.
Note
The default scope (if scope is omitted or an error) is the start URL, with its filename, query, and fragment removed.

8.7 icons member

The icons member is an array of ImageResources that can serve as iconic representations of the web application in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.

If there are multiple equally appropriate icons in icons, a user agent MUST use the last one declared in order at the time that the user agent collected the list of icons. If the user agent tries to use an icon but that icon is determined, upon closer examination, to in fact be inappropriate (e.g. because its content type is unsupported), then the user agent MUST try the next-most-appropriate icon as determined by examining the ImageResource's members.

In the following example, the developer has made the following choices about the icons associated with the web application:

  • The developer has included two icons at the same size, but in two different formats. One is explicitly marked as WebP through the type member. If the user agent doesn't support WebP, it falls back to the second icon of the same size. The MIME type of this icon can then be either determined via a HTTP header, or can be sniffed by the user agent once the first few bytes of the icon are received.
  • The developer wants to use an SVG for greater than or equal to 257x257px. She has found that the SVG file looks too blurry at small sizes, even on high-density screens. To deal with this problem, she's included an SVG icon that is only used when the dimensions are at least 257px. Otherwise, the user agent uses the ICO file (hd_hi.ico), which includes a gamut of raster icons individually tailored for small display sizes.
{
  "icons": [
    {
      "src": "icon/lowres.webp",
      "sizes": "48x48",
      "type": "image/webp"
    },{
      "src": "icon/lowres",
      "sizes": "48x48"
    },{
      "src": "icon/hd_hi.ico",
      "sizes": "72x72 96x96 128x128 256x256"
    },{
      "src": "icon/hd_hi.svg",
      "sizes": "257x257"
    }]
}

8.8 display member

WebIDLenum DisplayModeType {
  "fullscreen",
  "standalone",
  "minimal-ui",
  "browser"
};

The display member is a DisplayModeType, whose value is one of display modes values. The item represents the developer's preferred display mode for the web application.

8.9 orientation member

The orientation member is a string that serves as the default orientation for all top-level browsing contexts of the web application. The possible values are those of the OrientationLockType enum defined in [SCREEN-ORIENTATION].

If the user agent honors the value of the orientation member as the default orientation, then that serves as the default orientation for the life of the web application (unless overridden by some other means at runtime). This means that the user agent MUST return the orientation to the default orientation any time the orientation is unlocked [SCREEN-ORIENTATION] or the top-level browsing context is navigated.

Although the specification relies on the [SCREEN-ORIENTATION]'s OrientationLockType, it is OPTIONAL for a user agent to implement the [SCREEN-ORIENTATION] API. Supporting the [SCREEN-ORIENTATION] API is, of course, RECOMMENDED.

Certain UI/UX concerns and/or platform conventions will mean that some screen orientations and display modes cannot be used together. Which orientations and display modes cannot be used together is left to the discretion of implementers. For example, for some user agents, it might not make sense to change the default orientation of an application while in browser display mode.

Note

Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [SCREEN-ORIENTATION] API).

8.10 start_url member

The start_url member is a string that represents the start URL , which is URL that the developer would prefer the user agent load when the user launches the web application (e.g., when the user clicks on the icon of the web application from a device's application menu or homescreen).

The start_url member is purely advisory, and a user agent MAY ignore it or provide the end-user the choice not to make use of it. A user agent MAY also allow the end-user to modify the URL when, for instance, a bookmark for the web application is being created or any time thereafter.

The steps for processing the start_url member are given by the following algorithm. The algorithm takes a USVString value, a URL manifest URL, and a URL document URL. This algorithm returns a URL.

  1. If value is the empty string, return document URL.
  2. Let start URL be the result of parsing value, using manifest URL as the base URL.
  3. If start URL is failure:
  4. If start URL is not same origin as document URL:
    1. Issue a developer warning that the start_url needs to be same origin as the Document of the top-level browsing context.
    2. Return document URL.
  5. Otherwise, return start URL.

For example, if the value of start_url is ../start_point.html, and the manifest's URL is https://example.com/resources/manifest.webmanifest, then the result of URL parsing would be https://example.com/start_point.html.

8.10.1 Privacy consideration: start_url tracking

It's conceivable that the start_url could be crafted to indicate that the application was launched from outside the browser (e.g., "start_url": "index.html?launcher=homescreen"). This can be useful for analytics and possibly other customizations. However, it is also conceivable that developers could encode strings into the start_url that uniquely identify the user (e.g., a server assigned UUID). This is fingerprinting/privacy sensitive information that the user might not be aware of.

Given the above, it is RECOMMENDED that, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify the start URL of an application.

8.11 theme_color member

The theme_color member serves as the default theme color for an application context. What constitutes a theme color is defined in [HTML].

If the user agent honors the value of the theme_color member as the default theme color, then that color serves as the theme color for all browsing contexts to which the manifest is applied. However, a document may override the default theme color through the inclusion of a valid [HTML] meta element whose name attribute is "theme-color".

The steps for processing the theme_color member are given by the following algorithm. The algorithm takes a USVString theme color as an argument. This algorithm returns a USVString?.

Issue 760: Color processing steps are incorrect bug

We currently rely on [[CSS-SYNTAX-3]] "parse a component value", but that's an internal algorithm that's participating in a larger parser... it also skips of preconditions that the parser requires.

We've asked the CSS working group for guidance.

  1. Let potential color be the result of running [CSS-SYNTAX-3]'s parse a component value algorithm with theme color as input. If parsing returns a syntax error, return undefined.
  2. Let color be the result of attempting to parse potential color as a CSS color, as per [CSS-SYNTAX-3]. If parsing fails:
    1. Issue a developer warning.
    2. Return undefined.
  3. Return color.

8.14 background_color member

The background_color member describes the expected background color of the web application. It repeats what is already available in the application stylesheet but can be used by the user agent to draw the background color of a web application for which the manifest is known before the files are actually available, whether they are fetched from the network or retrieved from disk.

The background_color member is only meant to improve the user experience while a web application is loading and MUST NOT be used by the user agent as the background color when the web application's stylesheet is available.

The steps for processing the background_color member are given by the following algorithm. The algorithm takes a USVString background color as an argument. This algorithm returns a USVString?.

  1. Let potential color be the result of running [CSS-SYNTAX-3]'s parse a component value algorithm with background color as input. If parsing returns a syntax error, return undefined.
  2. Let color be the result of attempting to parse potential color as a CSS color, as per [CSS-SYNTAX-3]. If parsing fails:
    1. Issue a developer warning.
    2. Return undefined.
  3. Return color.

8.15 categories member

The categories member describes the expected application categories to which the web application belongs.

The categories member is only meant as a hint to catalogs or stores listing web applications and it is expected that these will make a best effort to find appropriate categories (or category) under which to list the web application. Like search engines and meta keywords, catalogs and stores are not required to honor this hint.

The steps for processing the categories member are given by the following algorithm. The algorithm takes a sequence<USVString> categories as an argument. This algorithm returns an Array<USVString>.

  1. For each category of categories:
    1. Replace category within categories with category, ascii lowercased.
  2. Return categories.

The categories string array is case insensitive and converted to lower-case by following the processing algorithm. Thus, sports, Sports, SPORTS, and SpOrTs are all equivalent.

Note

Manifest authors are encouraged to use lower-case.

Note

This specification does not define the particular values for USVStrings for the categories member. However, the working group maintains a list of known values in our wiki.

8.16 screenshots member

The screenshots member is an array of ImageResources, representing the web application in common usage scenarios.

8.17 iarc_rating_id member

The iarc_rating_id member is a string that represents the International Age Rating Coalition (IARC) certification code of the web application. It is intended to be used to determine which ages the web application is appropriate for.

Note

An IARC certificate can be obtained via participating storefronts, intended to be used for distributing the web app. The iarc_rating_id member only takes a single certification code. The same code can be shared across participating storefronts, as long as the distributed product remains the same (i.e., doesn’t serve totally different code paths depending on user agent sniffing and the like) and the other storefronts support it.

The following shows a very simple manifest with the iarc_rating_id member.

Example 10: very simple manifest
{
  "name": "Donate App",
  "description": "This app helps you donate to worthy causes.",
  "iarc_rating_id": "e84b072d-71b3-4d3e-86ae-31a8ce4e53b7",
  "icons": [{
    "src": "images/icon.png",
    "sizes": "192x192"
  }]
}

More information on the IARC can be found at: How IARC Works and How developers can get their games and apps rated with IARC.

8.18 shortcuts member

The shortcuts member is an array of ShortcutItems that provide access to key tasks within a web application.

Note

Shortcuts could, for instance, be used to link directly to a user's timeline within a social media application or to their recent orders in an e-commerce context.

How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.

Note

Developers are encouraged to order their shortcuts by priority, with the most critical shortcuts appearing first in the array.

The steps for processing the shortcuts member are given by the following algorithm. The algorithm takes a sequence<ShortcutItem> shortcuts and a URL manifest URL. This algorithm returns a sequence<ShortcutItem>.

  1. Let processedShortcuts be a new Array object created as if by the expression [].
  2. For each shortcut (ShortcutItem) in the sequence:
    1. If shortcut["name"] or shortcut["url"] are undefined, or if shortcut["name"] is the empty string, issue a developer warning and continue.
    2. Set shortcut["icons"] to the result of running processing ImageResource members given shortcut["icons"] and manifest URL.
    3. Set shortcut["url"] to the result of parsing shortcut["url"] using manifest URL as the base URL. If the result is failure, issue a developer warning and continue.
    4. If shortcut["url"] is not within scope of manifest URL, issue a developer warning and continue.
    5. Append shortcut to processedShortcuts.
  3. Return processedShortcuts.

A user agent SHOULD expose shortcuts via interactions that are consistent with exposure of an application icon's context menu in the host operating system (e.g., right click, long press). A user agent SHOULD render the shortcuts in the same order as they are provided in the manifest. A user agent SHOULD represent the shortcuts in a manner consistent with exposure of an application icon's context menu in the host operating system. A user agent MAY truncate the list of shortcuts presented in order to remain consistent with the conventions or limitations of the host operating system.

In the following example, the developer has included two shortcuts. Assuming the the manifest's URL is https://example.com/manifest.webmanifest:

  • The first shortcut would be displayed with the text "Play Later". If the operating system supports icons for context menu items and it also supports SVG images for that purpose, the user agent would present https://example.com/icons/play-later.svg next to the text. When launched, the user agent would instantiate a new top-level browsing context and navigate to https://example.com/play-later.
  • The second shortcut would be displayed with the text "Subscriptions". When launched, the user agent would instantiate a new top-level browsing context and navigate to https://example.com/subscriptions?sort=desc.
{
  "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"
        }
      ]
    },
    {
      "name": "Subscriptions",
      "description": "View the list of podcasts you listen to",
      "url": "/subscriptions?sort=desc"
    }
  ]
}

9. ImageResource and its members

WebIDLdictionary ImageResource {
  required USVString src;
  DOMString sizes;
  USVString type;
  USVString purpose;
  USVString platform;
};

Each ImageResource represents an image that is used as part of a web application, suitable to use in various contexts depending on the semantics of the member that is using the object (e.g., an icon that is part of an application menu, etc.). For an image resource, this specification provides developers with a means of specifying the dimensions, and MIME type of an image (i.e., a "responsive image" solution [RESPIMG-USECASES]). A user agent can use these values to select an image that is best suited to display on the end-user's device or most closely matches the end-user's preferences.

User agents may modify the images associated with an ImageResource to better match the platform’s visual style before displaying it to the user, for example by rounding the corners or painting it in a specific color. It is recommended that developers prepare their image resources for such scenarios to avoid losing important information through, e.g., change of color or clipped corners.

9.1 Fetching image resources

To fetch the image associated with an ImageResource, the user agent MUST run the steps to fetch an image resource. The algorithm takes an image URL (ImageResource.src), the manifest URL, and the Document document from which the manifest was linked. It returns a Response:

  1. Let request be a new Request.
  2. Set the following properties of request:
    1. url is set to image URL.
    2. initiator is "manifest".
    3. type is "image".
    4. cors is "no-cors".
    5. referrer is manifest URL.
    6. client is document.
  3. Perform a fetch using request and return the response.

9.2 Content security policy of image resources

The security policy that governs whether a user agent can fetch an icon image is governed by the img-src directive [CSP3] associated with the manifest's owner Document.

For example, given the following img-src directive in the Content-Security-Policy HTTP header of the manifest's owner Document:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Security-Policy: img-src icons.example.com

<!doctype>
<html>
<link rel="manifest" href="manifest.webmanifest">

And given the following manifest.webmanifest:

{
  "name": "custom manifest",
  "start_url": "https://boo",
  "icons": [
    {
      "src": "//icons.example.com/lowres"
    },
    {
      "src": "//other.com/hi-res"
    }
  ]
}

The fetching of icon resources from icons.example.com/lowres would succeed, while fetching from other.com/hi-res would fail.

9.3 purpose member

The purpose member is an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are the icon purposes.

When an ImageResource is used as an icon, a developer can hint that the image is intended to serve some special purpose in the context of the host OS (i.e., for better integration). User agents SHOULD NOT use an icon other than for its stated purpose.

Note

For example, an icon with purpose "badge" could be used as a badge or pinned icon that is visually distinct, in color or form, from an application's launch icon. The user agent uses the value of the purpose member as a hint to determine where and how an ImageResource is displayed. Unless declared otherwise by the developer, a user agent can use an icon for any purpose.

The icon purposes are as follows:

badge:
A user agent can present this icon where space constraints and/or color requirements differ from those of the application icon.
maskable:
The image is designed with icon masks and safe zone in mind, such that any part of the image that is outside the safe zone can safely be ignored and masked away by the user agent.
any:
The user agent is free to display the icon in any context.
Note

If an icon contains multiple purposes, it could be used for any of those purposes. If none of the stated purposes are recognized, the icon is totally ignored. For example, if an icon has purpose "badge fizzbuzz", then it could be used as a badge, but if an icon has just the purpose "fizzbuzz", then it will be ignored.

The steps for processing the purpose member of an image are given by the following algorithm. The algorithm takes an ImageResource image. This algorithm returns a set or failure.

  1. If Type(image["purpose"]) is not String, or image["purpose"] consists solely of ascii whitespace, then return the set « "any" ».
  2. Let keywords be the result of split on ASCII whitespace image["purpose"].
  3. If keywords is empty, then return the set « "any" ».
  4. Let purposes be the empty set.
  5. For each keyword of keywords:
    1. Set canonicalKeyword to ascii lowercased keyword.
    2. If canonicalKeyword is not one of the icon purposes, or purposes contains keyword, then issue a developer warning and continue.
    3. Otherwise, append canonicalKeyword to purposes.
  6. If purposes is empty, then return failure.
  7. Return purposes.

In the following example, the web application is listing two icons to be used as a badge, one of which is specifically designed for the Android platform.

{
  "name": "News",
  "icons": [{
    "platform": "play",
    "purpose": "badge",
    "sizes": "16x16",
    "src": "icons/badges/android.png",
    "type": "image/png"
  }, {
    "purpose": "badge",
    "src": "icons/badges/safari.svg",
    "type": "image/svg"
  }]
}

9.4 Icon masks and safe zone

Some platforms have their own preferred icon shape, but as web applications should work across multiple platforms, it is possible to indicate that an icon can have a user-agent-specified mask applied by adding the maskable purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different masks and background colors in different places throughout the platform.

The safe zone is the area within a maskable icon which is guaranteed to always be visible, regardless of user agent preferences. It is defined as a circle with center point in the center of the icon and with a radius of 2/5 (40%) of the icon size, which means the smaller of the icon width and height, in case the icon is not square.

Note

Designers of maskable icons will want to make sure that all important parts are within the safe zone.

safe zone illustrated
Figure 2 The safe zone is a centrally positioned circle, with radius 2/5 (40%) of the minimum of the icon's width and height.

All pixels in this zone are guaranteed to be seen in all masks. Pixels outside the safe zone are not guaranteed to (but can) be visible depending on the applied mask.

The user agent MAY apply a mask of any size, making any pixels that are more than 2/5ths of the image size (minimum of width and height if non-square) away from the center (the safe zone) transparent.

The user agent MUST NOT make any pixel within the safe zone transparent.

The user agent MAY enlarge the icon by adding additional padding.

If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid color (eg. white) of the user agent's choice.

Note

It is suggested that designers avoid using transparent pixels in maskable icons.

9.4.1 Examples of masks

Note

By staying inside the safe zone, most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.

Icons with "maskable" purpose

An icon over a checkerboard background
Figure 3 Image The base image with transparent background
An icon in a purple circle (40% of the size) over a yellow background
Figure 4 Safe zone Circle with radius 2/5 (40%) of the icon size

Mask examples

An icon inside a rounded yellow square on a purple background
Figure 5 Rounded square Android
An icon inside an extremely rounded yellow square on a purple background
Figure 6 Squircle Android
An icon inside a rounded yellow circle on a purple background
Figure 7 Circle Android
An icon inside a somewhat rounded yellow square on a purple background
Figure 8 Rounded square iOS
An icon on a yellow background
Figure 9 Fullbleed Windows

9.5 sizes member

The sizes member of an ImageResource is a string consisting of an unordered set of unique space-separated tokens which are ASCII case-insensitive that represents the dimensions of an image. Each keyword is either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The keywords represent icon sizes in raw pixels (as opposed to CSS pixels). When multiple ImageResources are available, a user agent MAY use the value to decide which icon is most suitable for a display context (and ignore any that are inappropriate).

The steps for processing the sizes member of an image are given by the following algorithm. The algorithm takes an ImageResource image. This algorithm will return a set.

  1. Let set be an empty set.
  2. Let value be image.sizes.
  3. If Type(value) is not String, return undefined.
  4. Otherwise, parse value as if it was a [HTML] sizes attribute and let list keywords be the result.
  5. For each keyword of keywords:
    1. append keyword, ascii lowercased, to set.
  6. Return set.

9.6 src member

The src member of an ImageResource is a URL from which a user agent can fetch the image's data.

9.7 type member

The type member of an ImageResource is a hint as to the MIME type of the image. The purpose of this member is to allow a user agent to ignore images of MIME types it does not support.

There is no default MIME type for image resources. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

The steps for processing the type member of an image are given by the following algorithm. The algorithm takes an image object as an argument, and returns either a string or undefined.

  1. Let value be image["type"].
  2. If Type(value) is not String, return undefined.
  3. If value is not a valid MIME type string or the value of type is not a supported MIME type, issue a developer warning and return undefined.
  4. Return value.

9.8 platform member

The platform member represents the platform to which a containing object applies.

9.9 processing an array of image resources

The steps for processing ImageResource members are given by the following algorithm. The algorithm takes a Array<ImageResource> entries and a URL manifest URL. This algorithm returns an Array<ImageResource>.

  1. Let imageResources be a new Array object created as if by the expression [].
  2. For each entry of entries:
  3. If entry["src"] is not undefined:
    1. Let image be a new object created as if by the expression ({}).
    2. Set image["src"] to the result of parsing entry["src"] using manifest URL as the base URL.
    3. Set image["type"] to the result of running processing the type member of an image given entry and manifest URL.
    4. Set image["sizes"] to the result of running processing the sizes member of an image given entry and manifest URL.
    5. Let purpose be the result of running processing the purpose member of an image given entry and manifest URL.
    6. If purpose is failure, continue.
    7. Set image["purpose"] to purpose.
    8. Set image["platform"] to entry["platform"].
    9. append image to imageResources
  4. Return imageResources.

10. ShortcutItem and its members

WebIDLdictionary ShortcutItem {
  required USVString name;
  USVString short_name;
  USVString description;
  required USVString url;
  sequence<ImageResource> icons;
};

Each ShortcutItem represents a link to a key task or page within a web app. A user agent can use these values to assemble a context menu to be displayed by the operating system when a user engages with the web app's icon. When the user invokes a shortcut from the operating system menu, the user agent SHOULD run Launching a shortcut.

10.1 name member

The name member of a ShortcutItem is a string that represents the name of the shortcut as it is usually displayed to the user in a context menu.

10.2 short_name member

The short_name member of a ShortcutItem is a string that represents a short version of the name of the shortcut. It is intended to be used where there is insufficient space to display the full name of the shortcut.

10.3 description member

The description member of a ShortcutItem is a string that allows the developer to describe the purpose of the shortcut. User agents MAY expose this information to assistive technology.

10.4 url member

The url member of a ShortcutItem is the URL within the application's scope that opens when the associated shortcut is activated.

10.5 icons member

The icons member of an ShortcutItem member is an array of ImageResources that can serve as iconic representations of the shortcut in various contexts.

10.6 Launching a shortcut

When ShortcutItem shortcut having WebAppManifest manifest is invoked, run the following steps:

  1. Let url be shortcut.url.
  2. Let browsing context be the result of creating a new top-level browsing context.
  3. Navigate browsing context to url.

11. Multi-purpose members

This section specifies members that can be used on multiple objects. Each member specifies which object a multi-purpose member can be used with.

11.1 platform member

The platform member represents the platform to which a containing object applies.

The following object types can make use of this member:

A platform represents a software distribution ecosystem or possibly an operating system.

Note

This specification does not define the particular values for a the platform member. However, the working group maintains a list of known platform values in our wiki.

12. ExternalApplicationResource and its members

WebIDLdictionary ExternalApplicationResource {
  required USVString platform;
  USVString url;
  DOMString id;
  USVString min_version;
  sequence<Fingerprint> fingerprints;
};

Each ExternalApplicationResources represents an application related to the web application. An application resource has the following properties:

platform
the platform it is associated to.
url
the URL where the application can be found.
id
information additional to the URL or instead of the URL, depending on the platform.
min_version
information about the minimum version of an application related to this web app.
fingerprints
an array of Fingerprint objects used for verifying the application.

A valid ExternalApplicationResource dictionary MUST have platform and either an url or an id (or both).

In the following example, the web application is listing two different related applications, one on Google Play Store and the other one on the iTunes Store. The one on the Google Play Store has an Android package name, a minimum version specifier, and cryptographic fingerprints used for verification, in a Play-Store-specific manner.

{
  "related_applications": [
    {
      "platform": "play",
      "url": "https://play.google.com/store/apps/details?id=com.example.app1",
      "id": "com.example.app1",
      "min_version": "2",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2"
        }
      ]
    },
    {
      "platform": "itunes",
      "url": "https://itunes.apple.com/app/example-app1/id123456789"
    }
  ]
}
Issue

Where should the platform expected value be listed?

12.1 url member

The url member of an ExternalApplicationResource dictionary represents the URL at which the application can be found.

The steps for processing the url member of an application are given by the following algorithm. The algorithm takes a USVString application URL. This algorithm will return an URL or undefined.

  1. If application URL is undefined, return undefined.
  2. Otherwise, parse application URL and if the result is not failure, return the result, otherwise return undefined.

12.2 id member

The id member of an ExternalApplicationResource dictionary represents the id which is used to represent the application on the platform.

12.3 min_version member

The min_version member of an ExternalApplicationResource dictionary represents the minimum version of the application that is considered related to this web app. This version is a string with platform-specific syntax and semantics.

12.4 fingerprints member

WebIDLdictionary Fingerprint {
  USVString type;
  USVString value;
};

The fingerprints member of an ExternalApplicationResource dictionary represents an array of Fingerprints.

Each Fingerprints represents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two properties: type and value. Each of these are strings, but their syntax and semantics are platform-defined.

13. IANA considerations

The following registrations are for community review and will be submitted to the IESG for review, approval, and registration with IANA.

13.1 Media type registration

This section contains the required text for MIME media type registration with IANA.

The MIME type for a manifest is application/manifest+json.

If the protocol over which the manifest is transferred supports the [MIME-TYPES] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the MIME type for a manifest.

Type name:
application
Subtype name:
manifest+json
Required parameters:
N/A
Optional parameters:
N/A
Encoding considerations:
Same as for application/json
Security and privacy considerations:

This specification does not directly deal with high-value data. However, installed web applications and their data could be seen as "high value" (particularly from a privacy perspective).

As the manifest format is JSON and will commonly be encoded using [UNICODE], the security considerations described in [ECMA-404] and [UNICODE-SECURITY] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest, implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [CSS-MIME], [ECMAScript-MIME], [HTML].

As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.

As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [URL] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [UNICODE-SECURITY].

Developers need to be aware of the security considerations discussed throughout the [CSP3] specification, particularly in relation to making data: a valid source for the purpose of inlining a manifest. Doing so can enable XSS attacks by allowing a manifest to be included directly in the document itself; this is best avoided completely.

Applications that use this MIME type:
Web browsers
Additional information:
Magic number(s):
N/A
File extension(s):
.webmanifest
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
The Web Platform Working Group can be contacted at public-webapps@w3.org.
Intended usage:
COMMON
Restrictions on usage:
none
Author:
W3C's Web Platform Working Group.
Change controller:
W3C.

A. Acknowledgements

This document reuses text from the [HTML] specification, as permitted by the license of that specification.

Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.

Claudio Gomboli for icon example images.

B. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

There is only one class of product that can claim conformance to this specification: a user agent.

Note

Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.

B.1 Extensibility

This section is non-normative.

This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the extension point to hook into the steps for processing a manifest. Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.

To allow the community can easily find extensions, please add your extensions to the Extensions Registry.

When specifying a new member, don't override or monkey patch anything defined in this specification. Also, don't assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.

If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.

B.1.1 Proprietary manifest members

This section is non-normative.

Although proprietary extensions are undesirable, they can't realistically be avoided. As such, the RECOMMENDED way to add a new proprietary manifest member as an extension is to use a vendor prefix.

We encourage implementors to add proprietary extensions to our Extensions Registry. This allows the community to track what extensions vendors and/or the web community have defined and documented. Periodically, we will consider those extensions for standardization.

The following is an example of three hypothetical vendor extensions.

Example 16: vendor extensions
{
  ...
  "webkit_fancy_feature": "some/url/img",
  "moz_awesome_thing": { ... },
  "vendor_example_site_verification": "KEY_9864D0966935"
  ...
}

D. JSON Schema

Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org. It is licensed under Apache 2.0. It is kindly maintained by Mads Kristensen. If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.

E. Internationalization

It is expected that authors will localize the content of a manifest by using one of the following options:

Dynamically setting the language:
This can include, for instance, asking the end-user what their preferred language is and dynamically adding or replacing the manifest link relationship to the document based on that language preference (e.g., using a URL like "manifest.php?lang=fr").
Using content-negotiation, or geotargeting, etc. on the server:
The server that hosts the web application could attempt to predetermine the end-user's language by using geotargeting or by using content negotiation (e.g., using [RFC7540]'s "Accept-Language" header, or even a custom HTTP header).

Given the options above, developers need to be mindful of the end-user's privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user's preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [TLS] to reduce the chances of pervasive monitoring of their Web applications [RFC7258].

F. Use Cases and Requirements

This document attempts to address the Use Cases and Requirements for Installable Web Apps.

G. Issue Summary

H. IDL Index

WebIDL[Exposed=Window]
interface BeforeInstallPromptEvent : Event {
  constructor(DOMString type, optional EventInit eventInitDict = {});
  Promise<PromptResponseObject> prompt();
};

dictionary PromptResponseObject {
  AppBannerPromptOutcome userChoice;
};

enum AppBannerPromptOutcome {
  "accepted",
  "dismissed"
};

partial interface Window {
  attribute EventHandler onappinstalled;
  attribute EventHandler onbeforeinstallprompt;
};

dictionary WebAppManifest {
   TextDirectionType dir = "auto";
   DOMString lang;
   USVString name;
   USVString short_name;
   USVString description;
   sequence<ImageResource> icons;
   sequence<ImageResource> screenshots;
   sequence<USVString> categories;
   DOMString iarc_rating_id;
   USVString start_url;
   DisplayModeType display = "browser";
   OrientationLockType orientation;
   USVString theme_color;
   USVString background_color;
   USVString scope;
   sequence<ExternalApplicationResource> related_applications;
   boolean prefer_related_applications = "false";
   sequence<ShortcutItem> shortcuts;
};

enum TextDirectionType { "ltr", "rtl", "auto" };

enum DisplayModeType {
  "fullscreen",
  "standalone",
  "minimal-ui",
  "browser"
};

dictionary ImageResource {
  required USVString src;
  DOMString sizes;
  USVString type;
  USVString purpose;
  USVString platform;
};

dictionary ShortcutItem {
  required USVString name;
  USVString short_name;
  USVString description;
  required USVString url;
  sequence<ImageResource> icons;
};

dictionary ExternalApplicationResource {
  required USVString platform;
  USVString url;
  DOMString id;
  USVString min_version;
  sequence<Fingerprint> fingerprints;
};

dictionary Fingerprint {
  USVString type;
  USVString value;
};

I. Terms defined by reference

As the manifest uses the JSON format, this specification relies on the types defined in [ECMA-404] specification: namely object, array, number, string, true, false, and undefined. Strict type checking is not enforced by this specification. Instead, each member's definition specifies the steps required to process a particular member and what to do when a type does not match what is expected.

J. References

J.1 Normative references

[BCP47]
Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47
[BIDI]
Unicode Bidirectional Algorithm. Mark Davis; Aharon Lanin; Andrew Glass. Unicode Consortium. 4 February 2019. Unicode Standard Annex #9. URL: https://www.unicode.org/reports/tr9/tr9-41.html
[CSP3]
Content Security Policy Level 3. Mike West. W3C. 15 October 2018. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[CSS-MIME]
The text/css Media Type. H. Lie; B. Bos; C. Lilley. IETF. March 1998. Informational. URL: https://tools.ietf.org/html/rfc2318
[CSS-SYNTAX-3]
CSS Syntax Module Level 3. Tab Atkins Jr.; Simon Sapin. W3C. 16 July 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/css-syntax-3/
[CSSOM-VIEW]
CSSOM View Module. Simon Pieters. W3C. 17 March 2016. W3C Working Draft. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript Internationalization API Specification. Ecma International. URL: https://tc39.es/ecma402/
[ECMA-404]
The JSON Data Interchange Format. Ecma International. 1 October 2013. Standard. URL: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/
[ECMAScript-MIME]
Scripting Media Types. B. Hoehrmann. IETF. April 2006. Informational. URL: https://tools.ietf.org/html/rfc4329
[encoding]
Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
[FETCH]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[MEDIAQ]
Media Queries Level 4. Florian Rivoal; Tab Atkins Jr.. W3C. 5 September 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediaqueries-4/
[MIME-TYPES]
Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[mimesniff]
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RESPIMG-USECASES]
Use Cases and Requirements for Standardizing Responsive Images. Marcos Caceres; Mathew Marquis; Yoav Weiss; David Newton. W3C. 7 November 2013. W3C Note. URL: https://www.w3.org/TR/respimg-usecases/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC5646]
Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL: https://tools.ietf.org/html/rfc5646
[RFC7258]
Pervasive Monitoring Is an Attack. S. Farrell; H. Tschofenig. IETF. May 2014. Best Current Practice. URL: https://tools.ietf.org/html/rfc7258
[RFC7540]
Hypertext Transfer Protocol Version 2 (HTTP/2). M. Belshe; R. Peon; M. Thomson, Ed.. IETF. May 2015. Proposed Standard. URL: https://httpwg.org/specs/rfc7540.html
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[SCREEN-ORIENTATION]
The Screen Orientation API. Mounir Lamouri; Marcos Caceres; Johanna Herman. W3C. 22 January 2020. W3C Working Draft. URL: https://www.w3.org/TR/screen-orientation/
[SECURE-CONTEXTS]
Secure Contexts. Mike West. W3C. 15 September 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/secure-contexts/
[TLS]
The Transport Layer Security (TLS) Protocol Version 1.2. T. Dierks; E. Rescorla. IETF. August 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5246
[UNICODE]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Unicode Security Considerations. Mark Davis; Michel Suignard. Unicode Consortium. 19 September 2014. Unicode Technical Report #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

J.2 Informative references

[FULLSCREEN]
Fullscreen API Standard. Philip Jägenstedt. WHATWG. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[SERVICE-WORKERS-1]
Service Workers 1. Alex Russell; Jungkee Song; Jake Archibald; Marijn Kruisselbrink. W3C. 19 November 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/service-workers-1/