Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification defines a JSON-based file format 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 screen 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 section describes the status of this document at the time of its publication. 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/.
This document was published by the Web Applications Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
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 03 November 2023 W3C Process Document.
An application manifest is a [JSON] document that contains startup parameters and application defaults for when a web application is launched.
A manifest has an associated manifest URL, which is the [URL] from which the manifest was fetched.
A manifest can have any of the following members at its root, all of which are optional. The members can appear in any order.
background_color
dir
display
icons
lang
name
orientation
prefer_related_applications
related_applications
scope
short_name
shortcuts
start_url
theme_color
This section is non-normative.
This section shows how developers can make use of the various features of this specification.
This section is non-normative.
The following shows a typical manifest.
{
"lang": "en",
"dir": "ltr",
"name": "Super Racer 3000",
"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": "/",
"id": "superracer",
"start_url": "/start.html",
"display": "fullscreen",
"orientation": "landscape",
"theme_color": "aliceblue",
"background_color": "red"
}
This section is non-normative.
The example also shows how to use the link type "manifest" and how
to use other meta
and link
elements to give the web
application a fallback name and set of icons.
<!doctype>
<html>
<title>Racer 3K</title>
<!-- Startup configuration -->
<link rel="manifest" href="manifest.webmanifest">
<!-- Fallback application metadata for legacy browsers -->
<meta name="application-name" content="Racer3K">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<link rel="icon" sizes="512x512" href="hi_def.png">
This section is non-normative.
In the following example, the developer has made the following choices about the icons associated with the web application:
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.
{
"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"
}]
}
This section is non-normative.
In the following example, the developer has included two shortcuts. Assuming the manifest's URL is https://example.com/manifest.webmanifest:
{
"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"
}
]
},
{
"name": "Subscriptions",
"description": "View the list of podcasts you listen to",
"url": "/subscriptions?sort=desc"
}
]
}
This section is non-normative.
The scope
member tells the browser which documents are
part of a web application, and which are not - and hence, to which
set of web pages the manifest is "applied" when the user
navigates around a web site.
For example, {"scope": "/"}
means that the manifest applies to
every document in an origin. On the other hand, {"scope":
"/racer/"}
means that only documents within the path "/racer/" are
within scope: so "/racer/race1.html", "/racer/race2.html",
etc. would all be within scope, but "/elsewhere/" and
anything at the root "/" would be "out of scope" and the manifest
wouldn't apply to documents in those paths. Only one scope path is
supported. See 6.
Navigation scope for the technical details.
Applying a manifest means that any members that affect presentation found in the manifest will come into effect, such as display "fullscreen", or applying a particular screen orientation. As long as the application is navigated to URLs that are within scope, the browser will continue to apply the manifest. However, navigating the web applications "out of scope" will cause the manifest to no longer be applied, and the browser will apply its own defaults. This will cause, for example, the application to no longer be displayed in fullscreen, and instead be displayed as a regular web page in a browser tab. It's left up to implementers to decide how to deal with web pages being navigated in and out of scope. See 1.17.5 Applying the manifest for the technical details.
Finally, as it's possible that a user can install a web application
from any document within an origin, it's good practice to always
declare a scope
member in a manifest. If the
scope
member is missing from the manifest, then the
path of the start_url
member is used as a fallback.
And if the start_url
member is also missing, then the
document URL from which the web application is installed gets used
as the scope. To be sure you don't get any unexpected navigation
behavior, always include a scope
member preferably set
to "/"
.
The manifest's dir
member specifies the base
direction for the localizable members of the
manifest. The dir
member's value can be set to a
text-direction.
The localizable members are:
name
member.
short_name
member.
name
member.
short_name
member.
description
member.
The text-directions are the following, implying that the value of the localizable members is by default:
The text-direction list is the list « "ltr", "rtl", "auto" ».
When displaying the localizable members to an end-user, the use agent SHOULD:
To process the dir
member, given ordered map
json and ordered map manifest:
The manifest's lang
member is a string in the form of
a language tag that specifies the primary language for the
values of the manifest's localizable 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.
To process the lang
member, given ordered map
json and ordered map manifest:
false
, return.
The manifest's 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).
The name
member serves as the accessible name of an
installed web application.
When processing a manifest, the process a text member
algorithm is used to process the name
member.
The manifest's 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.
When processing a manifest, the process a text member
algorithm is used to process the short_name
member.
The manifest's scope
member is a string that
represents the navigation scope of this web
application's application context.
To process the scope
member, given ordered map
json and ordered map manifest:
The manifest's icons
member are images that 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 images 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 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 manifest image resource's members.
The manifest's display
member represents the developer's
preferred display mode for the web application. Its value is a
display mode.
To process the display
member, given ordered map
json and ordered map manifest:
The manifest's orientation
member is a string that
serves as the default screen orientation for all top-level
browsing contexts of the web application. The possible values are
those of the OrientationLockType
enum, which in this
specification are referred to as the orientation values
(i.e., "any", "natural", "landscape", "portrait", "portrait-primary",
"portrait-secondary", "landscape-primary", or "landscape-secondary").
If the user agent supports the value of the orientation
member as the default screen orientation, then that serves as
the default screen 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 screen 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, encouraged.
Certain UI/UX concerns and/or platform conventions will mean that
some screen orientations and 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 screen
orientation of an application while in browser
display
mode.
Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [SCREEN-ORIENTATION] API).
To process the orientation
member, given ordered map
json and ordered map manifest:
The manifest's 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.
To process the start_url
member, given ordered map
json, ordered map manifest, URL
manifest URL, and URL document URL:
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.
Additionally, developers MUST NOT use the start URL to include information that uniquely identifies a user (e.g., "?user=123" or "/user/123/", or "https://user123.foo.bar").
The manifest's id
member is a string that represents
the identity for the application. The identity takes
the form of a URL, which is same origin as the start URL.
The identity is used by user agents to uniquely identify the application universally. When the user agent sees a manifest with an identity that does not correspond to an already-installed application, it SHOULD treat that manifest as a description of a distinct application, even if it is served from the same URL as that of another application. When the user agent sees a manifest where manifest["id"] is equal with exclude fragment true to the identity of an already-installed application, it SHOULD be used as a signal that this manifest is a replacement for the already-installed application's manifest, and not a distinct application, even if it is served from a different URL than the one seen previously.
The identity can be used by a service that collects lists of web applications to uniquely identify applications.
The identity is processed like a URL but it doesn't point to a resource that can be navigated to, so it's not required to be within scope.
To process the id
member, given ordered map
json, ordered map manifest:
The manifest's 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 value is
"theme-color"
.
The user agent MAY ignore the theme color's alpha component based on the context. For example, in most environments, the theme color cannot be transparent.
Implementors MAY override the value defined by the
theme_color
member to support prefers-color-scheme.
When processing a manifest, the process a color member
algorithm is used to process the theme_color
member.
The manifest's
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.
background_color
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.
Implementors MAY override the value defined by the
background_color
member to support prefers-color-scheme.
When processing a manifest, the process a color member
algorithm is used to process background_color
member.
The manifest's shortcuts
member is an list of
shortcut items that provide access to key tasks within a web
application.
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.
To process the shortcuts
member, given ordered map
json, ordered map manifest, and
URL manifest URL:
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.
This section defines algorithms for processing a manifest, and applying a manifest.
A user agent MUST support the link type "manifest" and the associated steps for how to fetch and process the linked resource.
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 processing 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.
The processing 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 URL document URL, a URL manifest URL, and a byte sequence bodyBytes.
dir
member passing json and manifest.
lang
member passing json and manifest.
start_url
member passing json, manifest,
manifest URL, and document URL.
id
member passing json and manifest.
scope
member passing json, manifest, and
manifest URL.
display
member passing json and manifest.
orientation
member passing json,
manifest.
related_applications
member passing json
and manifest.
shortcuts
member passing json, manifest,
and manifest URL.
Only sRGB colors, and colors the user agent can convert to
sRGB without any outside knowledge (e.g., "AliceBlue"
), are
supported. For example, lab(…)
or color(display-p3, …)
can be
converted to sRGB without outside knowledge, but
color(--custom-profile, …)
would require finding a matching
"@color-profile" rule which cannot be specified in the manifest.
To process a color member, using ordered map json, ordered map map, and string member:
To process a text member, given ordered map json, ordered map map, and string member:
The processing a manifest steps are invoked by [HTML]'s
processing steps for the link
element, but MAY also be invoked
by the user agent to process a manifest without an associated
document.
In this case, to match the guarantees made by the corresponding steps in [HTML], the user agent SHOULD ensure that at least at some point in the past:
link
element
linkElement with a rel
of
manifest
and a href
that resolves to
manifest URL, and that
Origin
is
document URL's origin, and whose credentials mode is set to the CORS settings attribute credentials mode
for linkElement's crossorigin
attribute.
A processed manifest is applied to a top-level browsing context, meaning that the members of the processed 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 historyHandling set to "replace
". Otherwise, when
the application context is created, the user agent MUST
immediately navigate to the start URL with
historyHandling set to "replace
".
The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.
As specified for manifest
link relation, the manifest
is fetched and processed on every page load. When the processing a manifest is successful, user agents MAY apply updated manifest
to any current and future application contexts associated
with the application.
For the purpose of updating, the following member are security-sensitive members, as they are presented during installation and on launch surfaces:
User agents SHOULD NOT automatically apply changes to security-sensitive members without express permission from the user.
Instead, user agents SHOULD present changes to security-sensitive members with appropriate management options, so the user can make an informed decision about updating the web application.
The user agent MAY automatically apply the changes if the update does not contain changes to security-sensitive members.
Each manifest image resource is an image resource that is conceptually 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.).
A manifest image resource differs from a image resource in that
it can have an additional purpose
member.
User agents MAY modify the images associated with an manifest image resource 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.
The purpose
member is an
unordered set of unique space-separated tokens. The allowed
values are the icon purposes.
When a manifest image resource 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 icon purpose.
For example, an icon with purpose "monochrome" could
be used as a badge or pinned icon with a solid fill, visually
distinct from an application's full color launch icon. The user agent
uses the value of the purpose
member as a
hint to determine where and how an purpose
is displayed. Unless declared otherwise by the
developer, a user agent can use an icon for any purpose.
The icon purposes are as follows:
The icon purposes list is the list « "monochrome", "maskable", "any" ».
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
"monochrome fizzbuzz"
, then it could be used as a monochrome icon,
as "monochrome"
is a valid purpose. However, if an icon just has
the purpose "fizzbuzz"
, then it will be ignored.
To determine the purpose of an image, given ordered map json:
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
.
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.
Designers of maskable icons will want to make sure that all important parts are within the safe zone.
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 fill (e.g., white) of the user agent's choice.
It is suggested that designers avoid using transparent pixels in maskable icons.
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.
Some platforms enforce that icons be displayed with a solid fill such as a single color, where only the transparency of the icon can be declared in a manifest. As web applications need to work across multiple platforms, it is possible to indicate that an icon can have an user-agent-specified color applied by adding the monochrome purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different colors and padding in different places throughout the platform.
When presenting a monochrome icon, the user agent MUST NOT independently display the red component, green component, or blue component of a pixel. The user agent SHOULD display each pixel with its original alpha value, but with a red, green, and blue value of the user agent's choosing. It is RECOMMENDED that the user agent use the same color value for all pixels.
Designers of monochrome icons could set all pixels to black and only use transparency to create a silhouette of their icon.
The user agent MAY enlarge the icon by adding additional padding.
The user agent MAY add a background of any color behind transparent pixels, and SHOULD ensure that the background has sufficient contrast with the icon.
To process image resources, given list images, ordered map map, manifest URL and string member:
Each shortcut item is an ordered map that represents a link to a key task or page within a web app. It has the following members:
A user agent can use these members 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.
The shortcut item's name
member is a string that
represents the name of the shortcut as it is usually displayed to the
user in a context menu.
The shortcut item's short_name
member 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.
The shortcut item's description
member is a string
that allows the developer to describe the purpose of the shortcut.
User agents MAY expose this information to assistive technology.
The shortcut item's url
member is a URL within scope of a processed manifest that opens when the
associated shortcut is activated.
The shortcut item's icons
member lists images that serve as
iconic representations of the shortcut in various contexts.
When shortcut item shortcut having manifest is invoked, run the steps to launch a web application with manifest and shortcut.url.
To process a shortcut, given ordered map item and scope,:
The related_applications
member of this specification currently only has a single implementation. As such, it has been marked "at risk" as per the W3C Process, meaning that:
[The feature] may be removed before advancement to Proposed Recommendation without a requirement to publish a new Candidate Recommendation.
The Web Apps Working Group is seeking a second implementation in order to keep this feature in the specification.
Each external application resource represents an application related to the web application.
An external application resource can have the following members, some of which are required to be a valid external application resource:
fingerprints
member
id
member
min_version
member
platform
member
url
member
A valid external application resource MUST have platform
member, and either an url
or an id
member (or both).
The platform
member
represents the platform this external application resource is
associated with. A platform represents a
software distribution ecosystem or possibly an operating system. This
specification does not define the particular values for the
platform member.
An external application resource's url
member is the
URL where the application can be found.
To process the url
member of an application:
An external application resource's id
member represents the
id which is used to represent the application on the platform.
An external application resource's min_version
member
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.
An external application resource's fingerprints
member
represents an list of fingerprints.
A fingerprint represents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two members: type and value. Each of these are strings, but their syntax and semantics are platform-defined.
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. A web application that is installed is known as a installed web application. 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 launching a web application, 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.
The application's name is derived from either the
name
member or short_name
member.
When either the name
member or the
short_name
member is missing, empty, or the wrong type,
a user agent MAY use the name
member as a fallback for
the short_name
member or short_name
member
as the fallback for the name
member.
If the name
and short_name
members are
missing, empty, or the wrong type, a user agent MAY fallback to the
Document
to find suitable replacements for missing manifest
members (e.g., using application-name
in place of name
or short_name
). Alternatively, 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).
At the discretion of the operating system or user agent, run the steps to launch a web application with a processed manifest.
This would typically take place when the user selects an installed web app from an app launching UI surface e.g., a home screen, launcher or start menu.
The steps to launch a web application is given by the following algorithm. The algorithm takes a processed manifest manifest, an optional URL target URL, an optional POST resource POST resource and returns an application context.
target URL, if given, MUST be within scope of manifest.
Other specifications MAY replace this algorithm's steps with their own steps. This replacement will take effect for all invocations of launch a web application.
This algorithm is replaceable to allow an experimental launch_handler manifest field to configure the behavior of all web application launches. The replacement algorithm invokes create a new application context by default but under certain conditions behaves differently.
The steps to create a new application context is given by the following algorithm. The algorithm takes a processed manifest manifest, an optional URL target URL, an optional POST resource POST resource and returns an application context.
It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting 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.
User agents SHOULD provide a mechanism for the user to remove an installed web application 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.
A display mode, as defined in [MEDIAQUERIES-5], 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.
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.
Every display mode has a fallback chain, which is a list of display modes. The fallback chain for:
The steps for determining the web app's chosen display mode is given by the following algorithm. The algorithm takes a processed manifest manifest and returns a display mode.
The above loop is guaranteed to return a value before the assertion, due to the fact that browser is in every mode's fallback chain, and the requirement that all user agents support the browser display mode.
The display modes list is the list « "fullscreen", "standalone", "minimal-ui", "browser" ».
A user agent MUST reflect the applied display mode of the web
application in the 'display-mode
' media feature [MEDIAQUERIES-5].
A user agent will 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 application into
fullscreen, then the user agent would reflect this change to CSS and
scripts via the 'display-mode
' media feature.
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 be encoded using [UNICODE], the security considerations described in [JSON] 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.
It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting 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.
It's conceivable that a shortcut url
could be crafted
to indicate that the application was launched from outside the browser
(e.g., "url": "/task/?from=homescreen"
). It is also conceivable that
developers could encode strings into the 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.
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".
The display
member allows an origin some measure of control over a
user agent’s native UI. After taking over the full screen, it could
attempt to mimic the user interface of another application. This is
also facilitated by the 'display-mode'
media feature
[MEDIAQUERIES-5], through which a script can know the display mode of
a web application.
The mime type application/manifest+json
is the application manifest media type. Both the mime type and the
.webmanifest
file extension are
registered with the Internet Assigned Numbers Authority
(IANA).
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 application manifest media type.
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.
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.
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 processing 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 to 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.
This section is non-normative.
Although proprietary extensions are undesirable, they can't realistically be avoided. If a user agent chooses to interpret a member in the manifest JSON that is not specified in this document, it can do so, but with care.
We encourage implementors adding proprietary extensions to consider whether they could become a standard (i.e. if it would make sense for a second user agent on a different platform to make use of that member, even if no other user agent has expressed interest right now). If so, we ask authors to design the API in a vendor-neutral way, and propose it as a standard (see C. Incubations). If the new member is truly proprietary (i.e. will only ever make sense in the context of a proprietary ecosystem), use this process, and prefix it with the short name of that proprietary ecosystem to avoid name collisions.
Do not use vendor prefixes that you intend to later remove once it becomes a standard (those tend to stick around forever). Only use prefixes that will make sense now and into the future.
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 proprietary extensions.
{
...
"kpl_fancy_feature": "some/url/img",
"gmpc_awesome_thing": { ... },
"blitzly_site_verification": "KEY_9864D0966935"
...
}
In this example, we have deliberately chosen (made-up) names of things that could be external sites or services, not names of browsers or browser vendors. These are not vendor prefixes belonging to the browser that invented them; they are prefixes of proprietary services.
This section is non-normative.
Extensions to this specification are being incubated in parallel by the Web Community, some of which are shipping in multiple browsers. If two or more browser engines end up supporting an incubated feature, then those features will become part of this specification in the future - allowing them to become a standard the Web Platform:
BeforeInstallPrompt
and window.onappinstalled
event
BeforeInstallPrompt
event and window.onappinstalled
event
were originally part of this specification. However, they were
removed from the
specification because they did not have support from two or more
implementers. You can now find them in the BeforeInstallPrompt
event and window.onappinstalled
repository at the WICG.
share_target
member
share_target
member registers a web application as "target" for
share actions (e.g., for sharing a text, a URL, or a file). The
share_target
member is part of the Web Share Target
specification, being incubated at the WICG.
This section is non-normative.
Several members of the Web Application Manifest provide additional metadata related to how the web application may be presented in the context of a digital storefront, installation dialog, or other surfaces where the web application may be marketed or distributed. In an effort to support these use cases better, the following members have been moved into Web App Manifest - Application Information:
categories
description
iarc_rating_id
screenshots
This section is non-normative.
An extensive discussion of why we chose to use JSON instead of HTML
meta
/link
tags for this specification is available on GitHub and on the
www-tag
list. Below is a short summary of the key points raised in those
discussions.
The document format defined in this specification provides a unified
means of encapsulating metadata about a Web application in a way that
we hope will avoid existing pitfalls with both proprietary and
[HTML]'s meta
/link
tags. Those pitfalls include:
Although it would be unrealistic to think that this specification won't bring its own set of problems, externalizing this data in the form of a manifest solves the problems described above. These problems are solved by:
meta
tags are currently using, especially when a tag's value contains
several sub-values.
In addition, standardizing the functionality currently provided by the
various meta
tag-based solutions within the manifest solves the
problem of having tproprietary and standard [HTML] tags that all
achieve the same thing. Of course, this hinges on the standard actually
getting implemented by browsers and those browsers getting widely
deployed to users: if this happens, the Web community might be able to
retire many of the proprietary meta
tags plaguing the Web at the time
of writing. More information about the proprietary tags can be found in
the Use Cases and
Requirements for Installable Web Apps .
Lastly, this specification does not make the standardized solutions
found in [HTML] redundant. When members like the name
or icons
is
missing from the manifest, user agents can search in a manifest's owner
[HTML] document for things like icons and the application name (or a
user agent might even fallback to proprietary tags/metadata, if they
are present in a document).
This section is non-normative.
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.
This section is non-normative.
It is expected that authors will localize the content of a manifest by using one of the following options:
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].
This document attempts to address the Use Cases and Requirements for Installable Web Apps.
This section is non-normative.
The following are some significant changes that were made since First Public Working Draft:
This section is non-normative.
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.
Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.
application/manifest+json
§A.background_color
§1.15description
§3.3dir
§1.2display
§1.8fingerprints
§4.5lang
§1.3min_version
§4.4orientation
§1.9prefer_related_applications
§1.14purpose
§2.1related_applications
§1.13scope
§1.6shortcuts
§1.16start_url
§1.10theme_color
§1.12CSS
)
Document
interface
Document
)
request
)
crossorigin
attribute (for link
element)
href
attribute (for link
element)
link
element
meta
element
name
attribute (for meta
element)
rel
attribute (for link
element)
list
)
set
)
string
)
list
)
iteration
)
map
)
list
)
list
)
@media
)
OrientationLockType
enum
url
)
url
)
url
)
url
)
url
)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: