Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
To associate documents of a web application with a manifest, this
specification defines the manifest link type as a
declarative means for a document to be associated with a manifest.
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 http://www.w3.org/TR/.
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 Platform Working Group as a Working Draft. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All comments are welcome.
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 5 February 2004 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.
The group does not expect this document to become a W3C Recommendation. It is expected to become a W3C Note.
This document is governed by the 1 September 2015 W3C Process Document.
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",
"name": "Super Racer 2000",
"short_name": "Racer2K",
"icons": [{
"src": "icon/lowres",
"sizes": "64x64",
"type": "image/webp"
}, {
"src": "icon/hd_small",
"sizes": "64x64"
}, {
"src": "icon/hd_hi",
"sizes": "128x128",
"density": 2
}],
"splash_screens": [{
"src": "splash/lowres",
"sizes": "320x240"
}, {
"src": "splash/hd_small",
"sizes": "1334x750"
}, {
"src": "splash/hd_hi",
"sizes": "1920x1080",
"density": 3
}],
"scope": "/racer/",
"start_url": "/racer/start.html",
"display": "fullscreen",
"orientation": "landscape",
"theme_color": "aliceblue",
"background_color": "red"
}
link element to
link to a manifest
This section is non-normative.
Example of using a link element to associate a website
with a manifest. The example also shows how to use
[HTML]'s
link and meta elements to give the web
application a fallback name and set of icons.
<!doctype>
<html>
<title>Super Racer 2000</title>
<!-- Startup configuration -->
<link rel="manifest" href="manifest.webmanifest">
<!-- Fallback application metadata for legacy browsers -->
<meta name="application-name" content="Racer2K">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<link rel="icon" sizes="512x512" href="hi_def.png">
This document attempts to address the Use Cases and Requirements for Installable Web Apps .
A web application is installed if the user agent has provided 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 (see application context).
An example of installing would be a user agent that allows the end-user to add a shortcut to a web application on their device's homescreen (using the name and one of the icons found in the manifest). Then, when the end-user launches a web application through this explicit means, the manifest is applied to the browsing context prior to the start URL being loaded. This gives the user agent time to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application.
Alternatively, an application context can be launched through a deep link (a URL that is within scope of the installed web application); in which case, the manifest is applied and the deep link is loaded within the context of web application.
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:
name member and a suitable icon.
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.
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 is REQUIRED to 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, Awesome 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 and their corresponding fallback display modes are as follows:
fullscreen is standalone.
standalone is minimal-ui.
minimal-ui is browser.
browser display mode doesn't have a
fallback display mode (conforming
user agents are required to support the browser
display mode).
The fullscreen display mode is orthogonal
to, and works independently of, the [WHATWG-FULLSCREEN]
API. The fullscreen display mode affects
the fullscreen state of the browser window, while the [WHATWG-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.
'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.
Please note that the fullscreen display
mode is not directly related to the CSS
:fullscreen pseudo-class specified in the
[WHATWG-FULLSCREEN] API. 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 [WHATWG-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 [WHATWG-FULLSCREEN] API. 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:fullsceen{
...
}
A user agent MUST reflect the applied display mode of the web application via a CSS media query [MEDIAQ].
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 */
}
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.
Furthermore, by neglecting to define a scope member in the manifest, it's possible to put a web application into a display mode that persists cross-origin (for legacy reasons, this is the default behavior). In case where the navigation scope is unbounded, it is left to the user agent to either stop applying the manifest when a cross-origin navigation occurs or to show some sort of security warning to the user.
A resource is said to be associated with a manifest if the resource
representation, an HTML document, has a manifest link relationship.
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 | not allowed | Imports or links to a manifest. |
The media type for a manifest serves
as the default media type for resources associated with the
manifest link type.
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 element 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.
This section defines algorithms for obtaining, processing, and applying a manifest, and gives recommendations to implementers on how to react when the manifest is updated.
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 terminates 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.
Document of the top-level
browsing context, let manifest link be the first
link element in tree order whose
rel attribute contains the
token manifest.
null, terminate this
algorithm.
href attribute's value
is the empty string, then abort these steps.
href attribute, relative to
the element's base URL. If parsing
fails, then abort these steps.
manifest".
crossOrigin
attribute's value is 'use-credentials', then set
request's credentials to 'include'.
Authors are encouraged to use the HTTP cache directives to explicitly cache the manifest. For example, the following response would cause a cached manifest to be used 30 days from the time the response is sent:
HTTP/1.1 200 OK
Cache-Control: max-age=2592000
Content-Type: application/manifest+json
{
"lang": "en",
"name": "Super Racer 2000",
"start_url": "/start.html",
"display": "fullscreen",
"orientation": "landscape"
}
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, [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).
img-src
directive controls where the icon's images can be fetched
from.
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.
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 text string 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 .
"{}".
"{}".
start_url member with
manifest, manifest URL, and document
URL as arguments.
display member with
manifest as the argument.
orientation member with
manifest and display mode as arguments.
name member with manifest as the
argument.
lang member with manifest as the
argument.
short_name member with
manifest as the argument.
scope member with manifest, manifest
URL, document URL, start URL as
arguments.
related_applications member with
manifest as argument.
prefer_related_applications
member with manifest as argument.
theme_color member with
manifest as argument.
background_color member with
manifest as argument.
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.
Please note that 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 added
to home-screen or otherwise bookmarked.
The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.
The spec says that the user agent may "periodically check if the contents of a manifest has been modified (e.g., by honoring HTTP cache directives associated with the manifest or by checking for updates after the web application has been launched)."
Firstly, being able to periodically check the contents of the manifest requires that the manifest URL does not change. If the manifest URL changes, there's no way to know that any new manifest corresponds to the same app as the old manifest and the only way for the app's metadata to be updated is for the user to re-install the app.
The removal of the same-origin restriction on manifest URLs was intended mainly to allow CDNs to host the manifest on a separate origin to the app, but the above assumes that CDNs are well behaved in that they never change the URL of the manifest, or as a minimum provide a redirect. @slightlylate assures me that CDNs these days are well behaved and do not change URLs of resources. Does anyone have any additional data on that?
So assuming the manifest URL does not change, or at least provides redirects, the user agent can "periodically check the contents" of the manifest to see whether something has been updated. Then the spec says that "in the event that the members of the manifest have been updated, as determined by running the steps for processing a manifest and seeing if anything has changed, the user agent MAY update the metadata corresponding to the web application ".
Now during the "steps for processing the manifest" the spec says that the start_url must be checked to be same origin with the document URL, that is the document the app was installed from. The same is true for the scope property. If the user agent is just "periodically checking the contents" of the manifest, does it need to also keep a record of the URL of the document the app was installed from, in order to make these checks? Note that this URL may be different for every installation as an app can be installed from any page of the app.
So assuming that CDNs behave well, the manifest URL doesn't change, and we've stored the document URL, we can then periodically check the contents of the manifest. Does this work for authenticated manifest URLs too? How does the user agent get the necessary credentials to fetch the manifest? Is the check only done by the user agent when the user logs in and uses the app?
It sounds like the implementation in Chrome may also be based on some additional assumptions regarding a registered Service Worker scope, is that the case? @mounirlamouri ?
If the assumptions above are in fact assumptions made by the spec, do we need to write something in the spec about the fact that user agents do not expect the manifest URL to change, and that therefore CDNs are expected to keep the same URL for the manifest or provide a redirect?
By using the manifest URL, a user agent MAY periodically check if the contents of a manifest has been modified (e.g., by honoring HTTP cache directives associated with the manifest or by checking for updates after the web application has been launched). In the event that the members of the manifest have been updated, as determined by running the steps for processing a manifest and seeing if anything has changed, the user agent MAY update the metadata corresponding to the web application (e.g., by replacing the name, icons, navigation scope, or whatever other data has been changed).
In addition, even if the manifest has not been modified, the user agents MAY periodically check if resources referenced from a manifest (e.g., the icons) have been modified by honoring HTTP cache directives. If any resources have been modified, the user agent MAY replace any stale resources.
To avoid one application masquerading as another, it is RECOMMENDED that users be made aware of any such updates using implementation or platform specific conventions.
A manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched. A manifest consists of a top-level object that contains zero or more members. Each of the members are defined below, as well as how their values are processed.
Every manifest has an associated manifest URL, which the [URL] from which the manifest was fetched.
lang member
The lang
member is a language tag (string) that specifies the
primary language for the values of the manifest's name
and short_name members.
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, see also the
Maintenance Agency for ISO 3166 country codes). 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
manifest as an argument. This algorithm returns a string
or undefined.
lang".
undefined.
false, then:
undefined.
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).
The steps for processing the name member is
given by the following algorithm. The algorithm takes a
manifest as an argument. This algorithm returns a string
or undefined.
name".
undefined.
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.
The steps for processing the short_name
member is given by the following algorithm. The algorithm takes
a manifest as an argument. This algorithm returns a string
or undefined.
short_name".
undefined.
scope member
People are confused by the lack of examples relating to scope:
manifoldjs/ManifoldJS#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 manifest manifest, a
URL
manifest URL , a URL document URL, and a
URL start URL . This algorithm returns a
URL
or undefined.
scope".
undefined",
issue a developer warning
that the type is unsupported.
undefined.
undefined.
scope needs to be
same-origin as Document of the
application context.
undefined.
undefined.
splash_screens
member
An app might want to show its splash screen for a minimum amount of time.
The splash_screens member is
an array of image objects that can serve as a
loading screen for the web application. A splash screen indicates to
the end user that a loading process is occurring (in effect, that the
web application is being prepared by the user agent in the
background). As the splash_screens member is an array of
image objects, developers can use unique
image objects definitions to target minimum screen resolutions and
pixel densities.
This feature is primarily intended for user agents that take a
perceptible amount of time to self-initialize (e.g., take longer than
200ms to be able to render content) - as such, it is OPTIONAL for a user agent to display
a splash screen while the web application is being loaded. On
launching a web application, if displaying a splash screen, the user
agent MUST queue a
post-load task on the Document of the
start URL to remove the splashscreen, or,
alternatively can follow platform conventions for how long a splash
screen is displayed (e.g., a minimum of 1 second).
The splash_screens member is processed using the
steps for processing
an array of images.
icons member
The icons
member is an array of image objects 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.
The icons member is processed using the
steps for processing
an array of images.
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 image object's members.
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 (and density).
The media 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": "72x72",
"density": 2
}]
}
display member
The display
member is a string, whose value is one of display
modes values. The item represents the developer's preferred
display mode for the web application. When
the member is missing or erroneous, the user agent MUST use the fallback display
mode.
The steps for processing the display
member are given by the following algorithm. The algorithm
takes a manifest manifest as an argument, and returns a
string.
display" as the argument.
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.
Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [SCREEN-ORIENTATION] API).
The steps for processing the orientation
member are given by the following algorithm. The algorithm
takes a manifest manifest and
display mode display mode as an
argument, and returns a string.
orientation".
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 manifest manifest, a
URL
manifest URL , and a URL document URL. This
algorithm returns a URL.
start_url".
undefined",
issue a developer warning
that the type is unsupported.
start_url needs to be same-origin as Document of
the top-level browsing
context.
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.
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 [META-THEME-COLOR].
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 [HTML] meta element that conforms to
[META-THEME-COLOR]. A user agent MUST return the theme color to the
default theme color when there are no
meta elements that conform to [META-THEME-COLOR]
in a document, or the top-level browsing context
is navigated to a URL that is
within scope.
The steps for processing the theme_color
member are given by the following algorithm. The algorithm
takes a manifest as an argument. This algorithm returns a
string or undefined.
theme_color".
undefined.
undefined.
undefined.
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 manifest as an argument.
This algorithm returns a string or undefined.
background_color".
undefined.
undefined.
undefined.
Different platforms have different guidelines regarding their icon style, and an app may need to follow them to look "native".
Wrong style, even if slightly wrong, can create "uncanny valley", e.g. multiple OSes use square icons with rounded corners, but with a different radius. Icon with a wrong corner radius looks like an amateurish knock-off.
The spec currently only matches icons on size and density, but not style/theme, so sites would need to resort to user-agent sniffing if they wanted to serve system-specific icons.
A theoretical solution available in HTML, with help of Moz's nonstandard media queries, is:
<link rel=icon href="generic.png">
<link rel=icon media="all and -moz-windows-theme:luna-blue" href="xp.png">
<link rel=icon media="all and -moz-windows-theme:aero" href="vista.png">
Each image object 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, a splashscreen, etc.). For an image object, this specification provides developers with a means of specifying the dimensions, optimal pixel density, and media 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.
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": "http://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.
density member
The density member of an image object is the
device pixel density for which this image was designed. The device
pixel density is expressed as the number of dots per 'px' unit
(equivalent to a dppx as defined in [css3-values]). The value is a positive
number greater than 0. If the developer omits the value, the user
agent assumes the value 1.0.
The steps for processing a density
member of an image are given by the following algorithm. The
algorithm takes an image image object as an
argument and returns a positive number.
density as the argument returns false:
density" as the argument.
NaN, +∞, or less than or
equal to +0, then:
sizes member
The sizes
member of an image object 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 image objects
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 a sizes member
of an image are given by the following algorithm. The algorithm
takes an image object image. This algorithm
will return a set.
sizes" as the argument.
undefined",
issue a developer warning
that the type is unsupported.
undefined.
sizes attribute and let keywords
be the result.
src member
The src
member of an image object is a URL from which a user agent
can fetch the image's data.
The steps for processing the src member
of an image are given by the following algorithm. The algorithm
takes a image object icon, and a
URL
manifest URL , which is the URL from which the
manifest was fetched. This algorithm will return a
URL
or undefined.
src" as the argument.
undefined", issue a
developer warning that the type is unsupported.
undefined.
undefined.
type member
The type
member of an image object is a hint as to the media type
of the image. The purpose of this member is to allow a user agent to
ignore images of media types it does not support.
There is no default MIME type for image objects. 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.
type" as the argument.
undefined", issue a
developer warning that the type is unsupported.
undefined.
undefined.
The steps for processing an array of images are given by the following algorithm. The algorithm takes a manifest, a URL manifest URL, which is the URL from which the manifest was fetched, and a string that represents the member name of the member which contains the array of image objects. This algorithm returns a list of image objects, which can be empty.
false.
src member of an image
with potential image and manifest URL.
undefined, move onto
the next item in images (if any are left).
src, type,
sizes, and density. All properties
initially set to undefined.
src property to be
src.
type member of an image
passing potential image.
undefined, set
image's type property to be
type.
sizes member of an image
passing potential image.
undefined, set
image's sizes property to be
sizes.
density member of an image
are given by the passing potential image .
undefined, set
image's density property to be
value.
undefined:
Each application
object represents an application related to the web application.
An application object has three properties: a platform
which represents the platform it is associated to, a url
which represents the URL where the application can be found and an
id which can be used as an information additional to the
URL or instead of the URL, depending on the platform. A valid
application object 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:
{
"related_applications": [
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=com.example.app1",
"id": "com.example.app1"
}, {
"platform": "itunes",
"url": "https://itunes.apple.com/app/example-app1/id123456789",
}]
}
Where should the platform expected value be listed?
platform member
The platform member of an application object represents the platform on which the application can be found.
The steps for processing the platform
member of an application are given by the following algorithm.
The algorithm takes an application object
application. This algorithm will return a string or
undefined.
platform" as the argument.
undefined.
url member
The url member of an application object 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 an application object
application. This algorithm will return an
URL
or undefined.
url" as the argument.
undefined.
undefined.
id member
The id member of an application object represents the id which is used to represent the application on the platform.
The steps for processing the id member
of an application are given by the following algorithm. The
algorithm takes an application object
application. This algorithm will return a string or
undefined.
id" as the argument.
undefined.
The [[GetOwnProperty]] operation and the abstract operation hasOwnProperty , parseFloat(string) function, and the Type(x) notation are defined in [ECMASCRIPT].
When instructed to Trim(x), a user agent MUST behave as if [ECMASCRIPT]'s String.prototype.trim() function had been called on the string x.
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
null. 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.
The URL concept and URL parser are defined in [WHATWG-URL].
The default orientation concept and the
OrientationLockType enum, are defined in
[SCREEN-ORIENTATION].
The algorithm to parse a component value is defined in [CSS-SYNTAX-3].
The
manifest-src,
img-src, and
default-src directives are defined in
[CSP3].
The IsStructurallyValidLanguageTag and CanonicalizeLanguageTag abstract operations are defined in [ECMAS-402].
The following are defined in [FETCH]:
The following are defined in [HTML]:
link
element
rel attribute
a element
meta
element
area
element
name attribute
title
element
The following registrations are for community review and will be submitted to the IESG for review, approval, and registration with IANA.
This section contains the required text for MIME media type registration with IANA.
The media
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 media type for a manifest.
Lots of feedback here...
https://lists.w3.org/Archives/Public/public-privacy/2015JanMar/0118.html
cc @npdoty, who we need to work with to address the above...
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 [WHATWG-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.
A request to register the manifest link relation type
been submitted to IANA.
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, REQUIRED, and SHOULD are to be interpreted as described in [RFC2119].
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 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.
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. As such, the RECOMMENDED way to add a new proprietary manifest member as an extension is to use a vendor prefix.
The following is an example of two hypothetical vendor extensions.
{
...
"webkit_fancy_feature": "some/url/img",
"moz_awesome_thing": { ... }
...
}
link
and meta elements
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 to declare large number of proprietary 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).
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.
The note should include:
<link rel=manifest
href='manifest?lang=en'>
This document reuses text from the [HTML] specification, edited by Ian Hickson, as permitted by the license of that specification.
Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.