Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: gh-pages
3000 lines (2990 sloc) 125.843 kB
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>
Manifest for a web application
</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class=
"remove">
</script>
<script class='remove'>
//make tidy happy
var respecConfig = {
previousPublishDate: "2013-12-17",
specStatus: 'WD',
shortName: 'appmanifest',
subtitle: 'Living Document',
prevVersion: 'FPWD',
previousMaturity: "WD",
editors: [{
name: "Marcos Caceres",
company: "Mozilla Corporation",
companyURL: "https://mozilla.org/",
w3cid: 39125
}, {
name: "Kenneth Rohde Christiansen",
company: "Intel Corporation",
companyURL: "http://intel.com",
w3cid: 57705
}, {
name: "Mounir Lamouri",
company: "Google Inc.",
companyURL: "https://google.com",
w3cid: 45389
}, {
name: "Anssi Kostiainen",
company: "Intel Corporation",
companyURL: "http://intel.com",
w3cid: 41974
}],
wg: 'Web Applications (WebApps) Working Group',
wgURI: 'http://www.w3.org/2008/webapps/',
wgPublicList: 'public-webapps',
wgPatentURI: 'http://www.w3.org/2004/01/pp-impl/42538/status',
noLegacyStyle: true,
otherLinks: [{
key: 'Repository',
data: [{
value: 'We are on Github.',
href: 'https://github.com/w3c/manifest'
}, {
value: 'File a bug.',
href: 'https://github.com/w3c/manifest/issues'
}, {
value: 'Commit history.',
href: 'https://github.com/w3c/manifest/commits/gh-pages'
}, {
value: 'Mailing list.',
href: 'https://lists.w3.org/Archives/Public/public-webapps/'
}]
}, {
key: "Implementation status",
data: [{
value: "Gecko",
href: "https://bugzilla.mozilla.org/show_bug.cgi?id=997779"
}, {
value: "Blink",
href: "https://code.google.com/p/chromium/issues/detail?id=366145"
}]
}],
issueBase: "https://www.github.com/w3c/manifest/issues/",
githubAPI: "https://api.github.com/repos/w3c/manifest"
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This specification defines a JSON-based manifest that provides
developers with a centralized place to put metadata associated with a
web application. This 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.
</p>
<p>
Using this metadata, user agents can provide developers with means to
create user experiences that are more comparable to that of a native
application.
</p>
<p>
To associate documents of a web application with a manifest, this
specification defines the <code>manifest</code> link type as a
declarative means for a document to be associated with a manifest
(either directly in a HTML document or over the wire using
[[RFC5988]]).
</p>
</section>
<section id="sotd">
<div class="warning">
<p>
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). <strong>Implementors who are not taking part in the
discussions will find the specification changing out from under them
in incompatible ways.</strong> Vendors interested in implementing
this specification before it eventually reaches the Candidate
Recommendation phase should <a href=
"https://github.com/w3c/manifest/issues">subscribe to the repository
on GitHub</a> and take part in the discussions.
</p>
</div>
</section>
<section class="informative">
<h2>
Usage Examples
</h2>
<p>
This section shows how developers can make use of the various features
of this specification.
</p>
<section class="informative">
<h3>
Example manifest
</h3>
<p>
The following shows a typical <a>manifest</a>.
</p>
<pre class="example highlight json" title="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"
}
</pre>
</section>
<section class="informative">
<h3>
Using a <code>link</code> element to link to a manifest
</h3>
<p>
Example of using a <code>link</code> element to associate a website
with a <a>manifest</a>. The example also shows how to use [[!HTML]]'s
<code>link</code> and <code>meta</code> elements to give the web
application a fallback name and set of icons.
</p>
<pre class="example highlight html" title="linking to a manifest">
&lt;!doctype&gt;
&lt;html&gt;
&lt;title&gt;Store finder - search&lt;/title&gt;
&lt;!-- Startup configuration --&gt;
&lt;link rel="manifest" href="manifest.webmanifest"&gt;
&lt;!-- Fallback application metadata for legacy browsers --&gt;
&lt;meta name="application-name" content="Store Finder"&gt;
&lt;link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico"&gt;
&lt;link rel="icon" sizes="512x512" href="hi_def.png"&gt;
</pre>
</section>
</section>
<section>
<h2>
Installable web applications
</h2>
<p>
This document attempts to address the <cite><a href=
"https://w3c-webmob.github.io/installable-webapps/">Use Cases and
Requirements for Installable Web Apps</a></cite> .
</p>
<p>
A web application is <dfn>installed</dfn> if the user agent has
provided the end-user with a means of instantiating a new <a>top-level
browsing context</a> that has the manifest's members applied to it.
That is, the manifest's members, or their defaults, are in effect on
the <a>top-level browsing context</a> (see <a>application context</a>).
</p>
<p>
An example of <a title="installed">installing</a> 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 <a>start URL</a> 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.
</p>
<p>
Alternatively, an application context can be launched through a <a>deep
link</a> (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.
</p>
<section>
<h3>
Authority of the manifest's metadata
</h3>
<p>
When a <a>manifest</a> is linked from a <code>Document</code>, it
indicates to the user agent that the metadata is
<dfn>authoritative</dfn>: that is, the user agent SHOULD use the
metadata of the manifest instead of the one in the
<code>Document</code>. However, in cases where metadata is missing,
or in error, a user agent MAY fallback to the <code>Document</code>
to find suitable replacements for missing manifest members (e.g.,
using <code>application-name</code> in place of
<code>short_name</code>).
</p>
</section>
<section class="informative">
<h3>
Installability signals
</h3>
<p>
By design, this specification does not provide developers with an
explicit API to "install" a web application. Instead, a
<a>manifest</a> can serve as an <dfn>installability signal</dfn> to a
user agent that a web application can be <a>installed</a>.
</p>
<p>
Examples of <a title="installability signal">installability
signals</a> for a web application:
</p>
<ul>
<li>is <a>associated with a manifest</a> with at least a
<code>name</code> member and a suitable icon.
</li>
<li>is served over a secure network connection.
</li>
<li>has a sensible content security policy.
</li>
<li>is able to responsibly adapt to display on a variety of screen
sizes, catering for both mobile and desktop.
</li>
<li>is able to function without a network connection.
</li>
<li>is repeatedly used by the end-user over some extended period of
time.
</li>
<li>has been explicitly marked by the user as one that they value and
trust (e.g., by bookmarking or "starring" it).
</li>
</ul>
<p>
This list is not exhaustive and some <a title=
"installability signal">installability signals</a> might not apply to
all user agents. How a user agent makes use of these <a title=
"installability signal">installability signals</a> to determine if a
web application can be <a>installed</a> is left to implementers.
</p>
</section>
</section>
<section>
<h2>
Navigation scope
</h2>
<p>
A <dfn>navigation scope</dfn> is a [[!URL]] that represents the set of
URLs to which an <a>application context</a> can be navigated while the
manifest is <a>applied</a>. To determine if a URL is within the
<a>navigation scope</a>, the user agent MUST run the <a>within
scope</a> algorithm.
</p>
<p>
A string <var>targetURL</var> is said the be <dfn>within scope</dfn> of
<a>navigation scope</a> <var>scopeURL</var> if the following algorithm
returns <code>true</code>:
</p>
<ol>
<li>If <var>scopeURL</var> is <code>undefined</code> (i.e., it is
<a>unbounded</a> because of an error or it was not declared in the
manifest), return <code>true</code>.
</li>
<li>Let <var>target</var> be a new URL using <var>targetURL</var> as
input. If <var>target</var> is failure, return <code>false</code>.
</li>
<li>If <var>target</var> is <a>same origin</a> as <var>scope</var> and
<var>target</var>'s <code>pathname</code> starts with
<var>scope</var>'s <code>pathname</code>, return <code>true</code>.
</li>
<li>Otherwise, return <code>false</code>.
</li>
</ol>
<div class="issue" title="🐒 Monkey patch">
<p>
Enforcing the navigation scope depends on [[!HTML]]'s navigate
algorithm. As such, the following algorithm monkey patches [[!HTML]].
<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27653">Bug
27653</a> has been filed to address this.
</p>
</div>
<p>
The user agent MUST navigate the application context as per [[!HTML]]'s
navigate algorithm with exceptions enabled. If the URL of the resource
being loaded in the navigation is not <a>within scope</a> of the
navigation scope, then the user agent MUST behave as if the application
context is not <a>allowed to navigate</a> (this provides the ability
for the user agent to perform the navigation in a different browsing
context, or in a different user agent entirely). If during the handle
redirects step of HTML's <a title="navigated">navigate algorithm</a>
the redirect URL is not <a>within scope</a>, abort HTML's navigation
algorithm with a <code>SecurityError</code>.
</p>
<p>
A developer specifies the navigation scope via the
<a><code>scope</code></a> member. In the case where the
<a><code>scope</code></a> member is missing or in error, the navigation
scope is treated as <dfn>unbounded</dfn> (represented as the value
<code>undefined</code>). In such a case, the manifest is applied to all
URLs the application context is <a>navigated</a> to (see related
<a href="#navigation-scope-security-considerations">security
considerations</a>).
</p>
<section>
<h3 id="navigation-scope-security-considerations">
Security considerations
</h3>
<p>
When the navigation scope is <a>unbounded</a> and a <a>display
mode</a> other than <code>browser</code> is being applied, it is
RECOMMENDED that user agents signal to the end-user when security
and/or privacy sensitive navigations occur. The manner of signaling
is left up to implementers, but can include things like showing the
URL of the application context, dropping out of fullscreen to the
browser display mode. Examples of security and/or privacy sensitive
navigations include, but are not limited to:
</p>
<ul>
<li>the application context being <a>navigated</a> from a secure
connection to an insecure connection (or vice versa).
</li>
<li>the application context being <a>navigated</a> to a different
origin.
</li>
</ul>
<p>
This specification distinguishes between behavior in first-party and
third-party contexts. In particular, if a <code>scope</code> member
is declared in the manifest, it is not possible to navigate the
<a>top-level browsing context</a> to somewhere outside the scope
while the <a>manifest</a> is <a>applied</a> to the <a>top-level
browsing context</a>. That's not to say that the web application
cannot be navigated: just that the set of URLs to which the manifest
applies is restricted by the <a>navigation scope</a>.
</p>
</section>
<section>
<h3>
Deep links
</h3>
<div class="issue" data-number="363"></div>
<p>
A <dfn>deep link</dfn> is a URL that is <a>within scope</a> of an
<a>installed</a> web application.
</p>
<div class="note">
<p>
The concept of a <a>deep link</a> is useful in that it allows
hyperlinking from one installed application to another. This can be
from a native application to an <a>installed</a> web application
(and possibly vice versa!). Theoretically, this can provide
seamless context switching between native and web applications
through standard hyperlinks. And in the case where a particular web
application is not <a>installed</a>, the OS can just open the link
in the user's preferred web browser.
</p>
<p>
Implementers are encouraged make such context switching obvious to
the user, for example, by adhering to the human interface
guidelines of the underlying platform with respect to application
switching.
</p>
</div>
</section>
</section>
<section>
<h2>
Display modes
</h2>
<p>
A <dfn>display mode</dfn> 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.
</p>
<p>
Once a user agent applies a particular <a>display mode</a> to an
<a>application context</a>, it becomes the <dfn>default display
mode</dfn> for the <a>top-level browsing context</a> (i.e., it is used
as the display mode when the window is <a>navigated</a>). The user
agent MAY override the <a>default display mode</a> for security reasons
(e.g., the <a>top-level browsing context</a> is <a>navigated</a> to
another origin) and/or the user agent MAY provide the user with a means
of switching to another <a>display mode</a>.
</p>
<p>
When the <code>display</code> member is missing, or if there is no
valid <code>display</code> member, the user agent uses the
<code>browser</code> <a>display mode</a> as the <a>default display
mode</a>. As such, the user agent is REQUIRED to support the
<code>browser</code> <a>display mode</a>.
</p>
<p>
Each <a>display mode</a>, except <code>browser</code>, has a
<dfn>fallback display mode</dfn>, which is the <a>display mode</a> that
the user agent can try to use if it doesn't support a particular
<a>display mode</a>. If the user agent does support a <a>fallback
display mode</a>, then it checks to see if it can use that <a>display
mode</a>'s <a>fallback display mode</a>. This creates a fallback chain,
with the <a>default display mode</a> (<code>browser</code>) being the
last item in the chain.
</p>
<div class="example">
<p>
For example, Awesome Browser only supports the
<code>minimal-ui</code> and <code>browser</code> display modes, but a
developer declares that she wants <code>fullscreen</code> in the
manifest. In this case, the user agent will first check if it
supports <code>fullscreen</code> (it doesn't), so it falls back to
<code>standalone</code> (which it also doesn't support), and
ultimately falls back to <code>minimal-ui</code>.
</p>
</div>
<p>
The <dfn>display modes values</dfn> and their corresponding <a title=
"fallback display mode">fallback display modes</a> are as follows:
</p>
<dl>
<dt>
<dfn id="dm-fullscreen">fullscreen</dfn>
</dt>
<dd>
Opens the web application without any user agent chrome and takes up
the entirety of the available display area.
</dd>
<dd>
The <a>fallback display mode</a> for <code>fullscreen</code> is
<code>standalone</code>.
</dd>
<dt>
<dfn id="dm-standalone">standalone</dfn>
</dt>
<dd>
Opens the web application to look and feel like a standalone native
application. This can include the application having a different
window, its own icon in the application launcher, etc. In this mode,
the user agent will exclude UI elements for controlling navigation,
but can include other UI elements such as a status bar.
</dd>
<dd>
The <a>fallback display mode</a> for <code>standalone</code> is
<code>minimal-ui</code>.
</dd>
<dt>
<dfn id="dm-minimal-ui">minimal-ui</dfn>
</dt>
<dd>
This mode is similar to <a>fullscreen</a>, but provides the end-user
with some means to access a minimal set of UI elements for
controlling navigation (i.e., back, forward, reload, and perhaps some
way of viewing the document's address). A user agent can include
other platform specific UI elements, such as "share" and "print"
buttons or whatever is customary on the platform and user agent.
</dd>
<dd>
The <a>fallback display mode</a> for <code>minimal-ui</code> is
<code>browser</code>.
</dd>
<dt>
<dfn id="dm-browser">browser</dfn>
</dt>
<dd>
Opens the web application using the platform-specific convention for
opening hyperlinks in the user agent (e.g., in a browser tab or a new
window).
</dd>
<dd>
The <code>browser</code> <a>display mode</a> doesn't have a
<a>fallback display mode</a> (conforming user agents are required to
support the <code>browser</code> <a>display mode</a>).
</dd>
</dl>
<p class="note">
The <a>fullscreen</a> <a>display mode</a> is orthogonal to, and works
independently of, the [[WHATWG-FULLSCREEN]] API. The
<a><code>fullscreen</code></a> <a>display mode</a> 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 <a>display mode</a> set to
<a><code>fullscreen</code></a>, while
<code>document.fullScreenElement</code> returns <code>null</code>, and
<code>fullscreenEnabled</code> returns <code>false</code>.
</p>
<section>
<h3>
The <code>'display-mode'</code> media feature
</h3>
<p>
The <code><dfn>display-mode</dfn></code> media feature represents,
via a CSS media query [[!MEDIAQ]], the <a>display mode</a> of the web
application. This media feature applies to the top-level browsing
context and any child browsing contexts. Child browsing contexts
reflect the <a>display mode</a> of the <a>top-level browsing
context</a>.
</p>
<p>
A user agent MUST expose the '<code>display-mode</code>' 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 '<code>display-mode</code>' media feature.
</p>
<div class="note">
<p>
Please note that the <code>fullscreen</code> <a>display mode</a> is
not directly related to the CSS <code>:fullscreen</code>
pseudo-class specified in the [[WHATWG-FULLSCREEN]] API. The
<code>:fullscreen</code> pseudo-class matches exclusively when a
[[!HTML]] element is put into the fullscreen element stack.
However, a side effect of calling the
<code>requestFullscreen()</code> 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
<code>:fullscreen</code> and <code>(display-mode:
fullscreen)</code> will match.
</p>
<p>
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 <code>:fullscreen</code> pseudo class
will not match, but <code>(display-mode: fullscreen)</code> will
match. This is exemplified in CSS code below.
</p>
<pre class='example highlight'>
/* applies when the window is fullscreen */
@media all and (display-mode: fullscreen) {
...
}
/* applies when an element goes fullscreen */
#game:fullsceen{
...
}
</pre>
</div>
<dl>
<dt>
Value:
</dt>
<dd>
<a>fullscreen</a> | <a>standalone</a> | <a>minimal-ui</a> |
<a>browser</a>
</dd>
<dt>
Applies to:
</dt>
<dd>
visual media types
</dd>
<dt>
Accepts min/max prefixes:
</dt>
<dd>
No
</dd>
</dl>
<p>
A user agent MUST reflect the applied <a>display mode</a> of the web
application via a CSS media query [[!MEDIAQ]].
</p>
<section>
<h4>
Examples
</h4>
<p>
An example in CSS:
</p>
<pre class='example highlight'>
@media all and (display-mode: minimal-ui) {
/* ... */
}
@media all and (display-mode: standalone) {
/* ... */
}
</pre>
<p>
Accessing the display-mode media feature in ECMAScript through
<code>matchMedia()</code> of [[cssom-view]]:
</p>
<pre class="example highlight">
const standalone = matchMedia( '(display-mode: standalone)' );
standalone.onchange = (e) =&gt; {
/* handle changes to display mode */
}
if (standalone.matches) {
/* do standalone things */
}
</pre>
</section>
<section>
<h3>
Security and privacy considerations
</h3>
<p>
The <code>'display-mode'</code> media feature allows an origin
access to aspects of a user’s local computing environment and,
together with the <code>display</code> 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.
</p>
<p>
Furthermore, by neglecting to define a scope member in the
manifest, it's possible to put a web application into a <a>display
mode</a> 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.
</p>
</section>
</section>
</section>
<section>
<h3>
Associating a resource with a manifest
</h3>
<p>
A resource is said to be <dfn>associated with a manifest</dfn> if the
resource representation, an HTML document, has a <a href=
"#linking"><code>manifest</code> link relationship</a>.
</p>
<section id="linking">
<h3>
Linking to a manifest
</h3>
<p>
The <code>manifest</code> keyword can be used with a [[!HTML]]
<a><code>link</code> element</a>. This keyword creates an <a>external
resource link</a>.
</p>
<table border="1">
<tr>
<th rowspan="2">
Link type
</th>
<th colspan="2">
Effect on...
</th>
<th rowspan="2">
Brief description
</th>
</tr>
<tr>
<th>
<code><a title="link element">link</a></code>
</th>
<th>
<code><a title="a element">a</a></code> and <code><a title=
"area element">area</a></code>
</th>
</tr>
<tr>
<td>
<code><dfn title="rel-manifest" id=
"rel-manifest">manifest</dfn></code>
</td>
<td>
<a title="external resource link">External Resource</a>
</td>
<td>
not allowed
</td>
<td>
Imports or links to a <a>manifest</a>.
</td>
</tr>
</table>
<p>
The <a>media type for a manifest</a> serves as the default media type
for resources associated with the <code><a href=
"#rel-manifest">manifest</a></code> <a>link type</a>.
</p>
<p class="note">
In cases where more than one <a><code>link</code> element</a> with a
<code>manifest</code> link type appears in a <code>Document</code>,
the user agent uses the first <a><code>link</code> element</a> in
tree order and ignores all subsequent <a title=
"link element"><code>link</code> element</a> with a
<code>manifest</code> link type (even if the first element was
erroneous). See the <a>steps for obtaining a manifest</a>.
</p>
<p>
To obtain a manifest, the user agent MUST run the <a>steps for
obtaining a manifest</a>. 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 <code>document</code>).
</p>
<p>
A <a>manifest</a> is obtained and applied regardless of the
<a><code>media</code></a> attribute of the <a><code>link</code>
element</a> matches the environment or not.
</p>
</section>
</section>
<section>
<h2>
Manifest life-cycle
</h2>
<p>
This section defines algorithms for <a href="#obtaining">obtaining</a>,
<a href="#processing">processing</a>, and <a href=
"#applying">applying</a> a <a>manifest</a>, and gives recommendations
to implementers on how to react when the manifest is <a href=
"#updating">updated</a>.
</p>
<section id="obtaining">
<h3>
Obtaining a manifest
</h3>
<p>
The <dfn>steps for obtaining a manifest</dfn> are given by the
following algorithm. The algorithm, if successful, returns a
<a>processed manifest</a> and the <var>manifest URL</var>; otherwise,
it terminates prematurely and returns nothing. In the case of nothing
being return, the user agent MUST ignore the manifest declaration. In
running these steps, a user agent MUST NOT <a>delay the load
event</a>.
</p>
<ol>
<li>From the <code>Document</code> of the <a>top-level browsing
context</a>, let <var>manifest link</var> be the first
<a><code>link</code> element</a> in <a>tree order</a> whose <a><code>
rel</code> attribute</a> contains the token <code>manifest</code>.
</li>
<li>If <var>manifest link</var> is <code>null</code>, terminate this
algorithm.
</li>
<li>If <var>manifest link</var>'s <code>href</code> attribute's value
is the empty string, then abort these steps.
</li>
<li>Let <var>manifest URL</var> be the result of <a title=
"URL parsing">parsing</a> the value of the <code>href</code>
attribute, relative to <a>the element's base URL</a>. If parsing
fails, then abort these steps.
</li>
<li>Let <var>request</var> be a new [[!FETCH]] <a>request</a>, whose
URL is <var>manifest URL</var>, and whose <a>context</a> is
"<code>manifest</code>".
</li>
<li>If the <var>manifest link</var>'s <code>crossOrigin</code>
attribute's value is '<code>use-credentials</code>', then set
<var>request</var>'s credentials to '<code>include</code>'.
</li>
<li>Await the result of performing a <a>fetch</a> with
<var>request</var>, letting <var>response</var> be the result.
</li>
<li>If <var>response</var> is a <a>network error</a>, terminate this
algorithm.
</li>
<li>Let <var>manifest</var> be the result of running the <a>steps for
processing a manifest</a> with <var>response</var>'s <a href=
"https://fetch.spec.whatwg.org/#concept-request-body">body</a> as the
<var>text</var>, <var>manifest URL</var>, and the URL that represents
the address of the <a title="top-level browsing context">top-level
browsing context</a>.
</li>
<li>Return <var>manifest</var> and <var>manifest URL</var>.
</li>
</ol>
<div class="note">
<p>
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 one year from the time the
response is sent:
</p>
<pre class="highlight">
HTTP/1.1 200 OK
Cache-Control: max-age=31536000
Content-Type: application/manifest+json
{
"lang": "en",
"name": "Super Racer 2000",
"start_url": "/start.html",
"display": "fullscreen",
"orientation": "landscape"
}
</pre>
</div>
<section>
<h4>
Content security policy
</h4>
<p>
A user agent MUST support [[!CSP3]].
</p>
<div class="example">
<p>
The <a><code>manifest-src</code></a> and
<a><code>default-src</code></a> directives govern the origins
from which a <a>user agent</a> can fetch a manifest. As with
other directives, by default the <a><code>manifest-src</code></a>
directive is <code>*</code>, meaning that a user agent can,
[[!CORS]] permitting, fetch the manifest cross-domain. Remote
origins (e.g., a <abbr title=
"content delivery network">CDN</abbr>) wanting to host manifests
for various web applications will need to include the appropriate
[[!CORS]] response header in their HTTP response (e.g.,
<code>Access-Control-Allow-Origin: https://example.com</code>).
</p>
<figure class="exaple">
<img src="images/manifest-src-directive.svg" width="704" height=
"342" alt="">
<figcaption>
For a [[!HTML]] document, [[!CSP3]]'s
<a><code>manifest-src</code></a> directive controls the sources
from which a [[!HTML]] document can load a manifest from. The
same CSP policy's <code>img-src</code> directive controls where
the icon's images can be fetched from.
</figcaption>
</figure>
</div>
</section>
</section>
<section id="processing">
<h3>
Processing the manifest
</h3>
<p>
When instructed to <dfn>issue a developer warning</dfn>, 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.
</p>
<p>
When instructed to <dfn>ignore</dfn>, the user agent MUST act as if
whatever manifest, member, or value caused the condition is absent.
</p>
<p>
The following algorithm provides an <dfn>extension point</dfn>: other
specifications that add new members to the manifest are encouraged to
hook themselves into this specification at this point in the
algorithm.
</p>
<div class="note">
<p>
The <a>extension point</a> is meant to help avoid <a href=
"https://annevankesteren.nl/2014/02/monkey-patch">issues related to
monkey patching</a>.
</p>
</div>
<p>
The <dfn>steps for processing a manifest</dfn> are given by the
following algorithm. The algorithm takes a <var>text</var> string as
an argument, which represents a <a>manifest</a>, and a <a>URL</a>
<var>manifest URL</var>, which represents the location of the
manifest, and a <a>URL</a> <var>document URL</var>. The output from
inputting an JSON document into this algorithm is a <dfn>processed
manifest</dfn> .
</p>
<ol>
<li>Let <var>parsed manifest</var> be an empty object.
</li>
<li>Let <var>manifest</var> be the result of <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-json.parse">
parsing</a> <var>text</var>. If <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-json.parse">
parsing</a> throws an error:
<ol>
<li>
<a>Issue a developer warning</a> with any details pertaining to
the JSON parsing error.
</li>
<li>Set <var>manifest</var> to be the result of <a href=
"https://people.mozilla.com/~jorendorff/es6-draft.html#sec-15.12.2">
parsing</a> the string <code>"{}"</code>.
</li>
</ol>
</li>
<li>If <a>Type</a>(<var>manifest</var>) is not "object":
<ol>
<li>
<a>Issue a developer warning</a> that the manifest needs to be
an object.
</li>
<li>Set <var>manifest</var> to be the result of <a href=
"https://people.mozilla.com/~jorendorff/es6-draft.html#sec-15.12.2">
parsing</a> the string <code>"{}"</code>.
</li>
</ol>
</li>
<li>
<a>Extension point</a>: process any proprietary and/or other
supported members at this point in the algorithm.
</li>
<li>Let <var>start URL</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>start_url</code> member</a> with <var>manifest</var>,
<var>manifest URL,</var> and <var>document URL</var> as arguments.
</li>
<li>Let <var>display mode</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>display</code> member</a> with <var>manifest</var> as the
argument.
</li>
<li>Let <var>orientation</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>orientation</code> member</a> with <var>manifest</var> and
<var>display mode</var> as arguments.
</li>
<li>Let <var>name</var> of <var>parsed manifest</var> be the result
of running the <a>steps for processing the <code>name</code>
member</a> with <var>manifest</var> as the argument.
</li>
<li>Let <var>language</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the <code>lang</code>
member</a> with <var>manifest</var> as the argument.
</li>
<li>Let <var>short name</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>short_name</code> member</a> with <var>manifest</var> as the
argument.
</li>
<li>Let <var>icons</var> of <var>parsed manifest</var> be the result
of running the <a>steps for processing an array of images</a> with
<var>manifest</var>, <var>manifest URL</var>, and "icons" as
arguments.
</li>
<li>Let <var>splash screens</var> of <var>parsed manifest</var> be
the result of running the <a>steps for processing an array of
images</a> with <var>manifest</var>, <var>manifest URL</var>, and
"splashscreen" as arguments.
</li>
<li>Let <var>scope</var> of <var>parsed manifest</var> be the result
of running the <a>steps for processing the <code>scope</code>
member</a> with <var>manifest</var>, <var>manifest URL</var>,
<var>document URL</var>, <var>start URL</var> as arguments.
</li>
<li>Let <var>related applications</var> of <var>parsed manifest</var>
be the result of running the <a>steps for processing the
<code>related_applications</code> member</a> with <var>manifest</var>
as argument.
</li>
<li>Let <var>prefer related applications</var> of <var>parsed
manifest</var> be the result of running the <a>steps for processing
the <code>prefer_related_applications</code> member</a> with
<var>manifest</var> as argument.
</li>
<li>Let <var>theme color</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>theme_color</code> member</a> with <var>manifest</var> as
argument.
</li>
<li>Return <var>parsed manifest</var>.
</li>
</ol>
</section>
<section>
<h3 id="applying">
Applying the manifest
</h3>
<p>
A <a>manifest</a> is <dfn>applied</dfn> to a <a>top-level browsing
context</a>, meaning that the members of the <a>manifest</a> are
affecting the presentation or behavior of a browsing context.
</p>
<p>
A <a>top-level browsing context</a> that has a manifest applied to it
is referred to as an <dfn>application context</dfn>.
</p>
<p>
If an <a>application context</a> is created as a result of the user
agent being asked to <a title="navigated">navigate</a> to a <a>deep
link</a>, the user agent MUST immediately <a title=
"navigated">navigate</a> to the <a>deep link</a> with <a>replacement
enabled</a>. Otherwise, when the <a>application context</a> is
created, the user agent MUST immediately <a title=
"navigated">navigate</a> to the <a>start URL</a> with <a>replacement
enabled</a>.
</p>
<div>
<p>
Please note that the <a>start URL</a> 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.
</p>
</div>
<p>
The appropriate time to <a title="applied">apply</a> a manifest is
when the <a>application context</a> is created and before <a title=
"navigated">navigation</a> to the <a>start URL</a> begins.
</p>
</section>
<section id="updating">
<h3>
Updating the manifest
</h3>
<div class="issue" data-number="384"></div>
<p>
By using the <a>manifest URL</a>, 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 <a>steps for processing a manifest</a> 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, <a>navigation scope</a>, or whatever other data has been
changed).
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
</section>
<section>
<h2>
Manifest and its members
</h2>
<p>
A <dfn>manifest</dfn> 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 <a title=
"json-object">object</a> that contains zero or more members. Each of
the members are defined below, as well as how their values are
processed.
</p>
<p>
Every manifest has an associated <dfn>manifest URL</dfn>, which the
[[!URL]] from which the <a>manifest</a> was fetched.
</p>
<section>
<h3>
<code title="">lang</code> member
</h3>
<p>
The <dfn id="member-lang"><code>lang</code></dfn> member is a
<a>language tag</a> (string) that specifies the primary language for
the values of the manifest's <code>name</code> and
<code>short_name</code> members.
</p>
<p>
A <dfn>language tag</dfn> is a string that matches the production of
a <code>Language-Tag</code> defined in the [[!BCP47]] specifications
(see the <a href=
"http://www.iana.org/assignments/language-subtag-registry">IANA
Language Subtag Registry</a> for an authoritative list of possible
values, see also the <a href=
"http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements">
Maintenance Agency for ISO 3166 country codes</a>). That is, a
language range is composed of one or more <dfn>subtags</dfn> that are
delimited by a U+002D HYPHEN-MINUS ("-"). For example, the
'<code>en-AU</code>' language range represents English as spoken in
Australia, and '<code>fr-CA</code>' 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.
</p>
<p>
The <dfn>steps for processing the <code>lang</code> member</dfn> is
given by the following algorithm. The algorithm takes a
<var>manifest</var> as an argument. This algorithm returns a string
or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>lang</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and let <var>tag</var>
be the result.
</li>
<li>If calling <a>IsStructurallyValidLanguageTag</a> with
<var>tag</var> as the argument returns <code>false</code>, then:
<ol>
<li>
<a>issue a developer warning</a> that the <var>value</var> is
invalid.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, return the result of calling the
<a>CanonicalizeLanguageTag</a> abstract operation, passing
<var>tag</var> as the argument.
</li>
</ol>
</section>
<section>
<h3>
<code title="">name</code> member
</h3>
<p>
The <dfn id="member-name"><code>name</code></dfn> member is a
<a title="json-string">string</a> 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).
</p>
<p>
The <dfn>steps for processing the <code>name</code> member</dfn> is
given by the following algorithm. The algorithm takes a
<var>manifest</var> as an argument. This algorithm returns a string
or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>name</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code title="">short_name</code> member
</h3>
<p>
The <dfn id="member-short_name"><code>short_name</code></dfn> member
is a <a title="json-string">string</a> 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.
</p>
<p>
The <dfn>steps for processing the <code>short_name</code>
member</dfn> is given by the following algorithm. The algorithm takes
a <var>manifest</var> as an argument. This algorithm returns a string
or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>short_name</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code>scope</code> member
</h3>
<div class="issue" data-number="380"></div>
<p>
The <dfn id="member-scope"><code>scope</code></dfn> member is a
string that represents the navigation scope of this web application's
<a>application context</a>.
</p>
<p>
The <dfn>steps for processing the <code>scope</code> member</dfn> is
given by the following algorithm. The algorithm takes a
<a>manifest</a> <var>manifest</var>, a <a>URL</a> <var>manifest
URL</var> , a <a>URL</a> <var>document URL</var>, and a URL
<var>start URL</var> . This algorithm returns a <a>URL</a> or
<code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of the <var>manifest</var>
with argument "<code>scope</code>".
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string" or <var>value</var> is the
empty string, then:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", <a>issue
a developer warning</a> that the type is unsupported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Let <var>scope URL</var> be a new <a>URL</a> using
<var>value</var> as <var>input</var> and <var>manifest URL</var> as
the <var>base</var> URL.
</li>
<li>If <var>scope URL</var> is failure:
<ul>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return <code>undefined</code>.
</li>
</ul>
</li>
<li>If <var>scope URL</var> is not <a href=
"https://www.whatwg.org/specs/web-apps/current-work/#same-origin">same
origin</a> as <var>document URL</var>:
<ol>
<li>
<a>Issue a developer warning</a> that the <code>scope</code>
needs to be <a href=
"https://www.whatwg.org/specs/web-apps/current-work/#same-origin">
same-origin</a> as <code>Document</code> of the <a>application
context</a>.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>If <var>start URL</var> is not <a>within scope</a> of scope URL:
<ol>
<li>
<a>Issue a developer warning</a> that the start URL is not
<a>within scope</a> of the navigation scope.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, return <var>scope URL</var>.
</li>
</ol>
</section>
<section>
<h3>
<code title="">splash_screens</code> member
</h3>
<div class="issue" data-number="372"></div>
<p>
The <dfn id="member-splash_screens"><code>splash_screens</code></dfn>
member is an <a title="json-array">array</a> of <a title=
"image object">image objects</a> 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 <code>splash_screens</code> member is an array of <a title=
"image object">image objects</a>, developers can use unique image
objects definitions to target minimum screen resolutions and pixel
densities.
</p>
<p>
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 <a>queue a post-load task</a> on the
<code>Document</code> of the <a>start URL</a> 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).
</p>
<p class="note">
The <code>splashscreen</code> member is processed using the <a>steps
for processing an array of images</a>.
</p>
</section>
<section>
<h3>
<code title="">icons</code> member
</h3>
<p>
The <dfn id="member-icons"><code>icons</code></dfn> member is an
<a title="json-array">array</a> of <a title="image object">image
objects</a> 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 <abbr title=
"operating system">OS</abbr>'s task switcher and/or system
preferences.
</p>
<p class="note">
The <code>icons</code> member is processed using the <a>steps for
processing an array of images</a>.
</p>
<p>
If there are multiple equally appropriate icons in <var>icons</var>,
a user agent MUST use the last one declared in order at the time that
the user agent collected the list of <var>icons</var>. 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 <a title=
"image object">image object's</a> members.
</p>
<div class="example">
<p>
In the following example, the developer has made the following
choices about the icons associated with the web application:
</p>
<ul>
<li>The developer has included two icons at the same size, but in
two different formats. One is explicitly marked as WebP through the
<code>type</code> 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.
</li>
<li>The developer wants to use an SVG icon for devices with at
least 2dppx as the display density and only when the available
dimensions are at least 72px. She has found that the SVG file looks
too blurry at small sizes, even on high-density screens. To deal
with this problem, she's included an SVG icon that is only used
when the dimensions are at least 72px and the pixel density is at
least 2dppx. Otherwise, the user agent uses the ICO file
(hd_hi.ico), which includes a gamut of icons individually tailored
for small display sizes.
</li>
</ul>
<pre class="">
{
"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
}]
}
</pre>
</div>
</section>
<section>
<h3>
<code>display</code> member
</h3>
<p>
The <dfn id="member-display"><code>display</code></dfn> member is a
<a title="json-string">string</a>, whose value is one of <a>display
modes values</a>. The item represents the developer's preferred
<a>display mode</a> for the web application. When the member is
missing or erroneous, the user agent MUST use the <a>fallback display
mode</a>.
</p>
<p>
The <dfn>steps for processing the <code>display</code> member</dfn>
are given by the following algorithm. The algorithm takes a manifest
<var>manifest</var> as an argument, and returns a string.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
passing "<code>display</code>" as the argument.
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string" or
<a>Trim</a>(<var>value</var>) is not part of the <a>display modes
values</a>:
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined", <a>issue
a developer warning</a> that the type is unsupported.
</li>
<li>If <var>value</var> is not part of the <a>display modes
values</a>, <a>issue a developer warning</a> that the value is
unsupported.
</li>
<li>Return the <a>fallback display mode</a>'s value.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and set <var>value</var>
to be the result.
</li>
<li>If <var>value</var> is not a <a>display mode</a> that the user
agent supports, set <var>value</var> to <var>value</var>'s
<a>fallback display mode</a> and re-run this step.
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>orientation</code> member
</h3>
<p>
The <dfn id="member-orientation"><code>orientation</code></dfn>
member is a <a title="json-string">string</a> that serves as the
<a>default orientation</a> for all <a title=
"top-level browsing context">top-level browsing contexts</a> of the
web application. The possible values are those of the
<a><code>OrientationLockType</code></a> enum defined in
[[!SCREEN-ORIENTATION]].
</p>
<p>
If the user agent honors the value of the <code>orientation</code>
member as the <a>default orientation</a>, then that serves as the
<a>default orientation</a> 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 <a>default
orientation</a> any time the orientation is unlocked
[[!SCREEN-ORIENTATION]] or the <a>top-level browsing context</a> is
<a>navigated</a>.
</p>
<p>
Although the specification relies on the [[!SCREEN-ORIENTATION]]'s
<a><code>OrientationLockType</code></a>, it is OPTIONAL for a user
agent to implement the [[!SCREEN-ORIENTATION]] API. Supporting the
[[!SCREEN-ORIENTATION]] API is, of course, RECOMMENDED.
</p>
<p>
Certain UI/UX concerns and/or platform conventions will mean that
some screen orientations and display modes <dfn>cannot be used
together</dfn> . 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 <a>default
orientation</a> of an application while in <code>browser</code>
<a>display mode</a>.
</p>
<p class="note">
Once the web application is running, other means can change the
orientation of a <a>top-level browsing context</a> (such as via
[[!SCREEN-ORIENTATION]] API).
</p>
<p>
The <dfn>steps for processing the <code>orientation</code>
member</dfn> are given by the following algorithm. The algorithm
takes a <a>manifest</a> <var>manifest</var> and <a>display mode</a>
<var>display mode</var> as an argument, and returns a string.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>orientation</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined", <a>issue
a developer warning</a> that the type is not supported.
</li>
<li>Return the empty string.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and set <var>value</var>
to be the result.
</li>
<li>If <var>value</var> is not one of the
<a><code>OrientationLockType</code></a> enum values, or
<var>value</var> is unsupported by the user agent, or the
<var>value</var> <a>cannot be used together</a> with <var>display
mode:</var>
<ol>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return the empty string.
</li>
</ol>
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>start_url</code> member
</h3>
<p>
The <dfn title="member-url"><code>start_url</code></dfn> member is a
<a title="json-string">string</a> that represents the <dfn>start
URL</dfn> , which is <a>URL</a> 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).
</p>
<p>
The <a title="member-url"><code>start_url</code></a> member is purely
advisory, and a user agent MAY <a>ignore</a> 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.
</p>
<p>
The <dfn>steps for processing the <code>start_url</code> member</dfn>
are given by the following algorithm. The algorithm takes a
<a>manifest</a> <var>manifest</var>, a <a>URL</a> <var>manifest
URL</var> , and a <a>URL</a> <var>document URL</var>. This algorithm
returns a <a>URL</a>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of the <var>manifest</var>
with argument "<code>start_url</code>".
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string" or <var>value</var> is the
empty string:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", <a>issue
a developer warning</a> that the type is unsupported.
</li>
<li>Return a new <a>URL</a> whose <var>input</var> is
<var>document URL</var>.
</li>
</ol>
</li>
<li>Let <var>url</var> be a new <a>URL</a> using <var>value</var> as
<var>input</var> and <var>manifest URL</var> as the <var>base</var>
URL.
</li>
<li>If <var>url</var> is failure:
<ul>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return a new <a>URL</a> whose <var>input</var> is
<var>document URL</var>.
</li>
</ul>
</li>
<li>If url is not <a>same origin</a> as <var>document URL</var>:
<ol>
<li>
<a>Issue a developer warning</a> that the
<code>start_url</code> needs to be <a>same-origin</a> as
<code>Document</code> of the <a>top-level browsing context</a>.
</li>
<li>Return a new <a>URL</a> whose <var>input</var> is
<var>document URL</var>.
</li>
</ol>
</li>
<li>Otherwise, return <var>url</var>.
</li>
</ol>
<div class="example">
<p>
For example, if the <var>value</var> of <code>start_url</code> is
<samp>../start_point.html</samp>, and the manifest's URL is
<samp>https://example.com/resources/manifest.webmanifest</samp>,
then the result of <a>URL parsing</a> would be
<samp>https://example.com/start_point.html</samp>.
</p>
</div>
</section>
<section>
<h3>
<code title="">theme_color</code> member
</h3>
<div class="warning" title="Feature at risk">
<p>
<strong>This feature is at risk of being removed from the
spec.</strong> We are asking people interested in this feature to
provide use cases for it. If you have any feedback, please comment
on <a href="https://github.com/w3c/manifest/issues/356">issue #356
- What's the use case for theme_color?</a> on GitHub.
</p>
</div>
<p>
The <dfn id="member-theme_color"><code>theme_color</code></dfn>
member serves as the <dfn>default theme color</dfn> for an
application context. What constitutes a <dfn>theme color</dfn> is
defined in [[!META-THEME-COLOR]].
</p>
<p>
If the user agent honors the value of the <code>theme_color</code>
member as the <a>default theme color</a>, then that color serves as
the <a>theme color</a> for all browsing contexts to which the
manifest is <a>applied</a>. However, a document may override the
<a>default theme color</a> through the inclusion of a [[!HTML]]
<code>meta</code> element that conforms to [[!META-THEME-COLOR]]. A
user agent MUST return the theme color to the <a>default theme
color</a> when there are no <code>meta</code> elements that conform
to [[!META-THEME-COLOR]] in a document, or the <a>top-level browsing
context</a> is <a>navigated</a> to a URL that is <a>within scope</a>.
</p>
<p>
The <dfn>steps for processing the <code>theme_color</code>
member</dfn> are given by the following algorithm. The algorithm
takes a <var>manifest</var> as an argument. This algorithm returns a
string or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>theme_color</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, let <var>potential color</var> be the result of
running [[!CSS-SYNTAX-3]]'s <a>parse a component value</a> algorithm
with <var>value</var> as input. If parsing returns a syntax error,
return <code>undefined</code>.
</li>
<li>Let <var>color</var> be the result of attempting to parse
<var>potential color</var> as a CSS color, as per [[!CSS-SYNTAX-3]].
If parsing fails:
<ol>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Return <var>color</var>.
</li>
</ol>
</section>
<section>
<h3>
<code title="">related_applications</code> member
</h3>
<p>
A <dfn>related application</dfn> is an application accessible to the
underlying application platform that has a relationship with the web
application <a>associated with a manifest</a>.
</p>
<p>
The <dfn id=
"member-related_applications"><code>related_applications</code></dfn>
member lists <a title="related application">related applications</a>
and serves as an indication of such a relationship between web
application and <a>related application</a>s. This relationship is
unidirectional and unless a listed application claims the same
relationship, the <a>user agent</a> MUST NOT assume a bi-directional
endorsement.
</p>
<p>
Example of usages of the <code>related_applications</code> could be a
crawler that would use that information to gather more information
about the web application or a browser that could suggest a listed
application as an alternative if the user wants to install the web
application.
</p>
<p>
The <dfn>steps for processing the <code>related_applications</code>
member</dfn> are given by the following algorithm. The algorithm
takes a manifest as an argument. This algorithm returns a list of
application objects <var>applications</var>, which can be empty.
</p>
<ol>
<li>Let <var>applications</var> be an empty list.
</li>
<li>Let <var>unprocessed applications</var> be the result of calling
the <a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>related_applications</code>".
</li>
<li>If <var>unprocessed applications</var> is an <a title=
"json-array">array</a>, then:
<ol>
<li>For each <var>potential application</var> in the array:
<ol>
<li>Let <var>platform</var> be the result of running the <a>
steps for processing the <code>platform</code> member of an
application</a> with <var>potential application</var>.
</li>
<li>If <var>platform</var> is <code>undefined</code>, move
onto the next item if any are left.
</li>
<li>Let <var>id</var> be the result of running the <a>steps
for processing the <code>id</code> member of an
application</a> with <var>potential application</var>.
</li>
<li>Let <var>url</var> be the result of running the <a>steps
for processing the <code>url</code> member of an
application</a> with <var>potential application</var>.
</li>
<li>If both <var>id</var> and <var>url</var> are
<code>undefined</code>, move onto the next item if any are
left.
</li>
<li>Otherwise, let <var>application</var> be an object with
properties <code>platform</code>, <code>id</code>,
<code>url</code> respectively set to <var>platform</var>,
<var>id</var> and <var>url</var>.
</li>
<li>Append <var>application</var> to <var>applications</var>.
</li>
</ol>
</li>
</ol>
</li>
<li>Otherwise, if <var>unprocessed applications</var> is not
<code>undefined</code>:
<ol>
<li>
<a>Issue a developer warning</a> that the type is not
supported.
</li>
</ol>
</li>
<li>Return <var>applications</var>.
</li>
</ol>
</section>
<section>
<h3>
<code title="">prefer_related_applications</code> member
</h3>
<div class="issue" data-number="365"></div>
<p>
The <dfn id=
"member-prefer_related_applications"><code>prefer_related_applications</code></dfn>
member is a boolean value that is used as a hint for the user agent
to say that <a title="related application">related applications</a>
should be preferred over the web application. The user agent MUST
consider the missing value as equivalent to have it set to
<code>false</code>. If the <code>prefer_related_applications</code>
is set to <code>true</code>, and the user agent wants to suggest to
install the web application, the user agent might want to suggest
installing one of the <a title="related application">related
applications</a> instead.
</p>
<p>
The <dfn>steps for processing the
<code>prefer_related_applications</code> member</dfn> are given by
the following algorithm. The algorithm takes a manifest as an
argument. This algorithm returns a boolean.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>prefer_related_applications</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "boolean":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>false</code>.
</li>
</ol>
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
</section>
<section>
<h2>
Image object and its members
</h2>
<div class="issue" data-number="361"></div>
<p>
Each <dfn>image object</dfn> 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.
</p>
<section>
<h3>
Content security policy of image objects
</h3>
<p>
The security policy that governs whether a <a>user agent</a> can
fetch an icon image is governed by the <code>img-src</code> directive
[[!CSP3]] associated with the manifest's owner <code>Document</code>.
</p>
<div class="example">
<p>
For example, given the following <code>img-src</code> directive in
the <code>Content-Security-Policy</code> HTTP header of the
manifest's owner <code>Document</code>:
</p>
<pre class="highlight">
HTTP/1.1 200 OK
Content-Type: text/html
Content-Security-Policy: img-src icons.example.com
&lt;!doctype&gt;
&lt;html&gt;
&lt;link rel="manifest" href="manifest.webmanifest"&gt;
</pre>
<p>
And given the following <code>manifest.webmanifest</code>:
</p>
<pre class="highlight">
{
"name": "custom manifest",
"start_url": "http://boo",
"icons": [{
"src": "//icons.example.com/lowres"
},
{
"src": "//other.com/hi-res"
}]
}
</pre>
<p>
The fetching of icon resources from
<code>icons.example.com/lowres</code> would succeed, while fetching
from <code>other.com/hi-res</code> would fail.
</p>
</div>
</section>
<section>
<h3>
<code>density</code> member
</h3>
<p>
The <dfn id="icon-densitiy">density</dfn> member of an <a>image
object</a> 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 <code>1.0</code>.
</p>
<p>
The <dfn>steps for processing a <code>density</code> member of an
image</dfn> are given by the following algorithm. The algorithm takes
an <var>image</var> <a>image object</a> as an argument and returns a
positive number.
</p>
<ol>
<li>If [[\HasOwnProperty]] internal method of <var>image</var>
passing <code>density</code> as the argument returns
<code>false</code>:
<ol>
<li>Return 1.0.
</li>
</ol>
</li>
<li>Let <var>value</var> be the result of calling the
[[\GetOwnProperty]] internal method of <var>image</var> passing "
<code>density</code>" as the argument.
</li>
<li>Let <var>result</var> be the result of <a>parseFloat</a>(
<var>value</var>);
</li>
<li>If <var>result</var> is <code>NaN</code>, +∞, or less than or
equal to +0, then:
<ol>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return 1.0.
</li>
</ol>
</li>
<li>Return <var>result</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>sizes</code> member
</h3>
<p>
The <dfn title="icon-sizes">sizes</dfn> member of an image object is
a <a title="json-string">string</a> consisting of an <a>unordered set
of unique space-separated tokens</a> which are <a>ASCII
case-insensitive</a> that represents the dimensions of an image. Each
keyword is either an <a>ASCII case-insensitive</a> match for the
string "<a>any</a>", or a value that consists of two <a title=
"valid non-negative integer">valid non-negative integers</a> 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 <a title=
"image object">image objects</a> 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).
</p>
<p>
The <dfn>steps for processing a <code>sizes</code> member of an
image</dfn> are given by the following algorithm. The algorithm takes
an <a>image object</a> <var>image</var>. This algorithm will return a
set.
</p>
<ol>
<li>Let <var>sizes</var> be an empty set.
</li>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>image</var>
passing " <code>sizes</code>" as the argument.
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string", then:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", <a>issue
a developer warning</a> that the type is unsupported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, parse <var>value</var> as if it was a [[!HTML]] <code>
<a>sizes</a></code> attribute and let <var>keywords</var> be the
result.
</li>
<li>For each <var>keyword</var> in <var>keywords</var>:
<ol>
<li>Convert <var>keyword</var> <a>to ASCII lowercase</a> and add
the resulting string to <var>sizes</var>.
</li>
</ol>
</li>
<li>Return <var>sizes</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>src</code> member
</h3>
<p>
The <dfn title="icon-src">src</dfn> member of an <a>image object</a>
is a <a>URL</a> from which a user agent can fetch the image's data.
</p>
<p>
The <dfn>steps for processing the <code>src</code> member of an
image</dfn> are given by the following algorithm. The algorithm takes
a <a>image object</a> <var>icon</var>, and a <a>URL</a> <var>manifest
URL</var> , which is the <a>URL</a> from which the
<var>manifest</var> was fetched. This algorithm will return a
<a>URL</a> or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>image</var>
passing " <code>src</code>" as the argument.
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string", then:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", issue a
developer warning that the type is unsupported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>If <a>Trim</a>(value) is the empty string, then return
<code>undefined</code>.
</li>
<li>Otherwise, <a title="URL parsing">parse</a> <var>value</var>
using <var>manifest URL</var> as the base URL and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code>type</code> member
</h3>
<p>
The <dfn title="icon-type">type</dfn> member of an <a>image
object</a> 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.
</p>
<p>
There is no default MIME type for image objects. However, for the
purposes of <a>determining the type of the resource</a>, user agents
must expect the resource to be an image.
</p>
<p>
The <dfn>steps for processing the <code>type</code> member of an
image</dfn> are given by the following algorithm. The algorithm takes
an <var>image</var> object as an argument, and returns either a
string or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>potential
image</var> passing "<code>type</code>" as the argument.
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string", then:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", issue a
developer warning that the type is unsupported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Trim(<var>value</var>) and set <var>value</var> to be resulting
string.
</li>
<li>If <var>value</var> is not a <a>valid MIME type</a> or the value
of <var>type</var> is not a supported media format, issue a developer
warning and return <code>undefined</code>.
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
<section>
<h3>
Processing an array of images
</h3>
<p>
The <dfn>steps for processing an array of images</dfn> are given by
the following algorithm. The algorithm takes a manifest, a <a>URL</a>
<var>manifest URL</var>, which is the URL from which the
<var>manifest</var> was fetched, and a string that represents the
<var>member name</var> of the member which contains the array of
<a title="image object">image objects</a>. This algorithm returns a
list of <a title="image object">image objects</a>, which can be
empty.
</p>
<ol>
<li>Let <var>images</var> be an empty list.
</li>
<li>Let <var>unprocessed images</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with <var>member name</var> as the argument.
</li>
<li>If <var>unprocessed images</var> is an <a title=
"json-array">array</a>, then:
<ol>
<li>From unprocessed images, filter out any <var>item</var> where
<a>HasOwnProperty</a>(item,"src") returns <code>false</code>.
</li>
<li>For each <var>potential image</var> in the array:
<ol>
<li>Let <var>src</var> be the result of running the <a>steps
for processing the <code>src</code> member of an image</a>
with <var>potential image</var> and <var>manifest URL</var>.
</li>
<li>If <var>src</var> is <code>undefined</code>, move onto
the next item in <var>images</var> (if any are left).
</li>
<li>Otherwise, let <var>image</var> be an object with
properties <code>src</code>, <code>type</code>,
<code>sizes</code>, and <code>density</code>. All properties
initially set to <code>undefined</code>.
</li>
<li>Set <var>image</var>'s <code>src</code> property to be
<var>src</var>.
</li>
<li>Let <var>type</var> be the result of running the <a>steps
for processing the <code>type</code> member of an image</a>
passing <var>potential image</var>.
</li>
<li>If <var>type</var> is not <code>undefined</code>, set
<var>image</var>'s <code>type</code> property to be
<var>type</var>.
</li>
<li>Let <var>sizes</var> be the list that result from running
the <a>steps for processing a <code>sizes</code> member of an
image</a> passing <var>potential image</var>.
</li>
<li>If <var>sizes</var> is not <code>undefined</code>, set
<var>image</var>'s <code>sizes</code> property to be
<var>sizes</var>.
</li>
<li>Let <var>density</var> be the result from running the <a>
steps for processing a <code>density</code> member of an
image</a> are given by the passing <var>potential
image</var> .
</li>
<li>If <var>density</var> is not <code>undefined</code>, set
<var>image</var>'s <code>density</code> property to be <var>
value</var>.
</li>
<li>Append <var>image</var> to <var>images</var>.
</li>
</ol>
</li>
</ol>
</li>
<li>Otherwise, if <var>unprocessed images</var> is not
<code>undefined</code>:
<ol>
<li>
<a>Issue a developer warning</a> that the type is not
supported.
</li>
</ol>
</li>
<li>Return <var>images</var>.
</li>
</ol>
</section>
</section>
<section>
<h2>
Application object and its members
</h2>
<p>
Each <dfn>application object</dfn> represents an application related to
the web application. An application object has three properties: a
<code>platform</code> which represents the platform it is associated
to, a <code>url</code> which represents the URL where the application
can be found and an <code>id</code> which can be used as an information
additional to the URL or instead of the URL, depending on the platform.
A valid <a>application object</a> MUST have <code>platform</code> and
either an <code>url</code> or an <code>id</code> (or both).
</p>
<div class="example">
<p>
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:
</p>
<pre class="">
{
"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",
}]
}
</pre>
</div>
<p class="issue">
Where should the <code>platform</code> expected value be listed?
</p>
<section>
<h3>
<code>platform</code> member
</h3>
<p>
The <dfn title="application-platform">platform</dfn> member of an
application object represents the platform on which the application
can be found.
</p>
<p>
The <dfn>steps for processing the <code>platform</code> member of an
application</dfn> are given by the following algorithm. The algorithm
takes an <a>application object</a> <var>application</var>. This
algorithm will return a string or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>application</var>
passing "<code>platform</code>" as the argument.
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code>url</code> member
</h3>
<p>
The <dfn title="application-url">url</dfn> member of an application
object represents the url at which the application can be found.
</p>
<p>
The <dfn>steps for processing the <code>url</code> member of an
application</dfn> are given by the following algorithm. The algorithm
takes an <a>application object</a> <var>application</var>. This
algorithm will return an <a>URL</a> or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>application</var>
passing "<code>url</code>" as the argument.
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Trim(<var>value</var>) and set <var>value</var> to be resulting
string.
</li>
<li>Otherwise, <a title="URL parsing">parse</a> <var>value</var> and
if the result is not failure, return the result, otherwise return
<code>undefined</code>.
</li>
</ol>
</section>
<section>
<h3>
<code>id</code> member
</h3>
<p>
The <dfn title="application-id">id</dfn> member of an application
object represents the id which is used to represent the application
on the platform.
</p>
<p>
The <dfn>steps for processing the <code>id</code> member of an
application</dfn> are given by the following algorithm. The algorithm
takes an <a>application object</a> <var>application</var>. This
algorithm will return a string or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>application</var>
passing "<code>id</code>" as the argument.
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
</section>
<section>
<h2>
Common conventions and dependencies
</h2>
<p>
The <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-ordinary-object-internal-methods-and-internal-slots-getownproperty-p">
<dfn>[[\GetOwnProperty]]</dfn></a> operation and the abstract operation
<dfn><a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-hasownproperty">
hasOwnProperty</a></dfn> , <dfn title="parseFloat"><a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-parsefloat-string">
parseFloat(string)</a></dfn> function, and the <a class="external"
href="https://people.mozilla.org/~jorendorff/es6-draft.html#sec-ecmascript-data-types-and-values">
<dfn>Type</dfn>(<var>x</var>)</a> notation are defined in
[[!ECMASCRIPT]].
</p>
<p>
When instructed to <dfn>Trim</dfn>(<var>x</var>), a user agent MUST
behave as if [[!ECMASCRIPT]]'s <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.trim">
String.prototype.trim()</a> function had been called on the string
<var>x</var>.
</p>
<p>
As the manifest uses the JSON format, this specification relies on the
types defined in [[!ECMA-404]] specification: namely <dfn title=
"json-object">object</dfn>, <dfn title="json-array">array</dfn>,
<dfn title="json-number">number</dfn>, <dfn title=
"json-string">string</dfn>, <code>true</code>, <code>false</code>, and
<code>null</code>. 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.
</p>
<p>
The <dfn><a href=
"https://url.spec.whatwg.org/#concept-url">URL</a></dfn> concept and
<dfn><a href="https://url.spec.whatwg.org/#url-parsing">URL
parsing</a></dfn> are defined in [[!WHATWG-URL]].
</p>
<p>
The <a href=
"https://w3c.github.io/screen-orientation/#dfn-default-orientation"><dfn>
default orientation</dfn></a> concept and the <a href=
"https://w3c.github.io/screen-orientation/#idl-def-OrientationLockType">
<dfn><code>OrientationLockType</code></dfn></a> enum, are defined in
[[!SCREEN-ORIENTATION]].
</p>
<p>
The algorithm to <a href=
"http://dev.w3.org/csswg/css-syntax/#parse-component-value"><dfn>parse
a component value</dfn></a> is defined in [[!CSS-SYNTAX-3]].
</p>
<p>
The <a href=
"https://w3c.github.io/webappsec/specs/content-security-policy/#manifest_src">
<dfn><code>manifest-src</code></dfn></a>, <a href=
"https://w3c.github.io/webappsec/specs/content-security-policy/#img_src">
<dfn><code>img-src</code></dfn></a>, and <a href=
"https://w3c.github.io/webappsec/specs/content-security-policy/#default_src">
<dfn><code>default-src</code></dfn></a> directives are defined in
[[!CSP3]].
</p>
<p>
The <a href=
"http://www.ecma-international.org/ecma-402/1.0/#sec-6.2.2"><dfn>IsStructurallyValidLanguageTag</dfn></a>
and <a href=
"http://www.ecma-international.org/ecma-402/1.0/#sec-6.2.3"><dfn>CanonicalizeLanguageTag</dfn></a>
abstract operations are defined in [[!ECMAS-402]].
</p>
<p>
The following are defined in [[!FETCH]]:
</p>
<ul>
<li>
<a href=
"https://fetch.spec.whatwg.org/#concept-fetch"><dfn>Fetch</dfn></a>.
</li>
<li>
<a href=
"https://fetch.spec.whatwg.org/#concept-response"><dfn>Response</dfn></a>.
</li>
<li>
<a href=
"https://fetch.spec.whatwg.org/#concept-request"><dfn>Request</dfn></a>.
</li>
<li>
<a href=
"https://fetch.spec.whatwg.org/#concept-network-error"><dfn>Network
error</dfn></a>.
</li>
<li>
<a href=
"https://fetch.spec.whatwg.org/#concept-request-context"><dfn>Context</dfn></a>
</li>
</ul>
<p>
The following are defined in [[!HTML]]:
</p>
<ul>
<li>
<a href=
"https://html.spec.whatwg.org/multipage/browsers.html#allowed-to-navigate">
<dfn>allowed to navigate</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#external-resource-link">
<dfn>external Resource link</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
<dfn>top-level browsing context</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#same-origin"><dfn>
same-origin</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#unordered-set-of-unique-space-separated-tokens">
<dfn>unordered set of unique space-separated tokens</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#navigate"><dfn>navigated</dfn></a>
</li>
<li>
<a href=
"https://html.spec.whatwg.org/multipage/browsers.html#replacement-enabled">
<dfn>replacement enabled</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element">
<dfn><code>link</code> element</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#linkTypes"><dfn>link
type</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-link-media">
<dfn>media</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#delay-the-load-event">
<dfn>delay the load event</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#tree-order"><dfn>
tree order</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#attr-link-rel"><dfn>
<code>rel</code> attribute</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#concept-link-obtain">
<dfn>obtain a resource</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#networking-task-source">
<dfn>networking task source</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#queue-a-task"><dfn>
queue a task</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#origin"><dfn>origin</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#the-a-element"><dfn>
<code>a</code> element</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#the-meta-element">
<dfn><code>meta</code> element</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#the-area-element">
<dfn><code>area</code> element</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#attr-meta-name"><dfn>
<code>name</code> attribute</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#meta-application-name">
<dfn>application-name</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#the-title-element">
<dfn><code>title</code> element</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#rel-icon"><dfn>icon
link type</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#ascii-case-insensitive">
<dfn>ASCII case-insensitive</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#attr-link-sizes-any">
<dfn>any</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#valid-non-negative-integer">
<dfn>valid non-negative integer</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#attr-link-sizes">
<dfn>sizes</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#converted-to-ascii-lowercase">
<dfn>to ASCII lowercase</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#concept-link-type-sniffing">
<dfn>determining the type of the resource</dfn></a>
</li>
<li>
<a href=
"https://www.whatwg.org/specs/web-apps/current-work/#valid-mime-type">
<dfn>valid MIME type</dfn></a>
</li>
<li>
<a href="https://html.spec.whatwg.org/#same-origin"><dfn>same
origin</dfn></a>
</li>
<li>
<a href=
"https://html.spec.whatwg.org/#the-element's-base-url"><dfn>the
element's base URL</dfn></a>.
</li>
<li>
<a href=
"https://html.spec.whatwg.org/#queue-a-post-load-task"><dfn>queue a
post-load task</dfn></a>
</li>
</ul>
</section>
<section>
<h2>
IANA considerations
</h2>
<p>
The following registrations are for community review and will be
submitted to the <a href="https://www.ietf.org/iesg/">IESG</a> for
review, approval, and registration with <a href=
"https://www.iana.org/">IANA</a>.
</p>
<section>
<h3>
Media type registration
</h3>
<p>
This section contains the required text for MIME media type
registration with <a href="https://www.iana.org/">IANA</a>.
</p>
<p>
The <dfn>media type for a manifest</dfn> is
<code>application/manifest+json</code>.
</p>
<p>
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 <a>media type for a manifest</a>.
</p>
<dl>
<dt>
Type name:
</dt>
<dd>
application
</dd>
<dt>
Subtype name:
</dt>
<dd>
manifest+json
</dd>
<dt>
Required parameters:
</dt>
<dd>
N/A
</dd>
<dt>
Optional parameters:
</dt>
<dd>
N/A
</dd>
<dt>
Encoding considerations:
</dt>
<dd>
Same as for application/json
</dd>
<dt>
Security and privacy considerations:
</dt>
<dd>
<div class="issue" data-number="348"></div>
<p>
This specification does not directly deal with high-value data.
However, <a>installed</a> web applications and their data could
be seen as "high value" (particularly from a privacy
perspective).
</p>
<p>
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 <a>manifest</a>, 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.
</p>
<p>
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]].
</p>
<p>
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.
</p>
<p>
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 <abbr title=
"Internationalized Resource Identifiers">IRIs</abbr> and
<abbr title="Internationalized domain name">IDNA</abbr> addresses
found in the manifest are strongly encouraged to follow the
security advice given in [[!UNICODE-SECURITY]].
</p>
<p>
Developers need to be aware of the security considerations
discussed throughout the [[!CSP3]] specification, particularly in
relation to making <code>data:</code> a valid source for the
purpose of <q>inlining</q> 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.
</p>
</dd>
<dt>
Applications that use this media type:
</dt>
<dd>
Web browsers
</dd>
<dt>
Additional information:
</dt>
<dd>
<dl>
<dt>
Magic number(s):
</dt>
<dd>
N/A
</dd>
<dt>
File extension(s):
</dt>
<dd>
.webmanifest
</dd>
<dt>
Macintosh file type code(s):
</dt>
<dd>
TEXT
</dd>
</dl>
</dd>
<dt>
Person &amp; email address to contact for further information:
</dt>
<dd>
The <a href="http://www.w3.org/2008/webapps/" rel="nofollow">Web
Applications (WebApps) Working Group</a> can be contacted at
<a href="https://lists.w3.org/Archives/Public/public-webapps/" rel=
"nofollow">public-webapps@w3.org</a>.
</dd>
<dt>
Intended usage:
</dt>
<dd>
COMMON
</dd>
<dt>
Restrictions on usage:
</dt>
<dd>
none
</dd>
<dt>
Author:
</dt>
<dd>
W3C's Web Applications (WebApps) Working Group.
</dd>
<dt>
Change controller:
</dt>
<dd>
W3C.
</dd>
</dl>
</section>
<section>
<h3>
Link relation type registration
</h3>
<p class="note">
A request to register the <code>manifest</code> link relation type
been submitted to IANA.
</p>
<dl>
<dt>
Relation Name:
</dt>
<dd>
manifest
</dd>
<dt>
Description:
</dt>
<dd>
Links to a <a>manifest</a>. A manifest provides developers with a
centralized place to put metadata associated with a web
application.
</dd>
<dt>
Reference:
</dt>
<dd>
<a href=
"http://www.w3.org/TR/appmanifest/">http://www.w3.org/TR/appmanifest/</a>
</dd>
<dt>
Notes:
</dt>
<dd>
Please refer to the <a>steps for obtaining a manifest</a> for
details about how to fetch and <a title="applied">apply</a> a
<a>manifest</a>.
</dd>
</dl>
</section>
</section>
<section id="conformance" data-status="done">
<p>
There is only one class of product that can claim conformance to this
specification: a <dfn>user agent</dfn>.
</p>
<p class="note">
Although this specification is primarily targeted at web browsers, it
is feasible that other software could also implement this specification
in a conforming manner. For instance, search engines, or crawlers,
could find and process manifests to build up catalogs of sites that
potentially work as <a title="installed">installable web
applications</a>.
</p>
<section class="informative">
<h3>
Extensibility
</h3>
<p>
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 <a>extension point</a> to hook into the
<a>steps for processing a manifest</a>. 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.
</p>
<p>
When specifying a new member, don't override or <a href=
"https://annevankesteren.nl/2014/02/monkey-patch">monkey patch</a>
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.
</p>
<p>
If you are writing a specification and temporarily want to patch this
specification to help implementations along, <a href=
"https://github.com/w3c/manifest/issues">file a bug</a> so the
community is informed of what you are trying to do.
</p>
<section id="proprietary-extensions" class="informative">
<h3>
Proprietary manifest members
</h3>
<p>
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.
</p>
<p>
The following is an example of two hypothetical vendor extensions.
</p>
<pre class="example highlight json" title="vendor extensions">
{
...
"webkit_fancy_feature": "some/url/img",
"moz_awesome_thing": { ... }
...
}
</pre>
</section>
</section>
</section>
<section class="appendix">
<h2>
Relationship to HTML's <code>link</code> and <code>meta</code> elements
</h2>
<p>
An extensive discussion of why we chose to use JSON instead of HTML
<code>meta</code>/<code>link</code> tags for this specification is
available on <a href=
"https://github.com/w3c/manifest/issues/97">GitHub</a> and on the
<a href=
"https://lists.w3.org/Archives/Public/www-tag/2014Jan/0139.html">www-tag</a>
list. Below is a short summary of the key points raised in those
discussions.
</p>
<p>
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 <code>meta</code>/<code>link</code> tags. Those pitfalls
include:
</p>
<ul>
<li>Developers have to duplicate the icons and application name in each
page of a web site, leading to significant redundancy across pages.
This is compounded if that information never gets used by the user
agent (e.g., the user never bookmarks the web application).
</li>
<li>Spreading metadata across multiple documents can cause data to fall
out of sync.
</li>
<li>If the metadata for a web application lives in a HTML document,
that significantly increases the cost to user agents (and users) of
checking for updates to the metadata of a site. Since the HTML file is
likely to change often, it means that a user agent will often have to
download the whole HTML file in order to check if any of the relevant
meta tags have changed. If this resource contains inlined resources
like JavaScript, images, or stylesheets, this could be a non-trivial
download.
</li>
</ul>
<p>
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:
</p>
<ul>
<li>Making the manifest externally linkable: External manifest files
can be cached as external resources, saving both bytes and redundancy
in the markup.
</li>
<li>Flexible value types: unlike HTML attributes, members of the
manifest can represent data using complex types, such as objects and
arrays, rather than just strings. This solves the problem of the
awkward and highly inconsistent formats the values of proprietary
<code>meta</code> tags are currently using, especially when a tag's
value contains several sub-values.
</li>
</ul>
<p>
In addition, standardizing the functionality currently provided by the
various <code>meta</code> 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
<code>meta</code> tags plaguing the Web at the time of writing. More
information about the proprietary tags can be found in the
<cite><a href="https://w3c-webmob.github.io/installable-webapps/">Use
Cases and Requirements for Installable Web Apps</a></cite> .
</p>
<p>
Lastly, this specification does not make the standardized solutions
found in [[!HTML]] redundant. When members like the <code>name</code>
or <code>icons</code> 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).
</p>
</section>
<section class="appendix">
<h2>
JSON Schema
</h2>
<p>
Developers interested in validating <a>manifest</a> documents can find
an unofficial <a href="http://json.schemastore.org/web-manifest">JSON
schema for the manifest format</a> at <a href=
"http://schemastore.org/">schemastore.org</a>. It is licensed under
<a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache
2.0</a>. It is kindly maintained by <a href=
"https://github.com/madskristensen">Mads Kristensen</a>. If you find
any issues with the JSON schema, please <a href=
"https://github.com/SchemaStore/schemastore/issues/">file a bug</a> at
the <a href="https://github.com/SchemaStore/schemastore">SchemaStore
repository</a> on GitHub.
</p>
</section>
<section id="internationalization">
<h2>
internationalization
</h2>
<div class="issue" data-number="323"></div>
</section>
<section id="issue-summary"></section>
<section class="appendix">
<h2>
Acknowledgments
</h2>
<p>
This document reuses text from the [[!HTML]] specification, edited by
Ian Hickson, as permitted by the license of that specification.
</p>
</section>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.