Copyright © 2019 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
This specification defines a JSON-based manifest file that provides developers with a centralized place to put metadata associated with a web application. This metadata includes, but is not limited to, the web application's name, links to icons, as well as the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to "scope" a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to "deep link" into a web application from other applications.
Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.
This
specification
also
defines
the
manifest
link
type
as
a
declarative
means
to
associate
a
document
with
a
manifest.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Implementors need to be aware that this specification is not stable. However, aspects of this specification are shipping in at least one browser (see links to implementation status at the top of this document). Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.
This document was published by the Web Applications Working Group as a Living Document.
GitHub Issues are preferred for discussion of this specification.
Publication as a Living Document does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 March 2019 W3C Process Document .
This section is non-normative.
This section shows how developers can make use of the various features of this specification.
This section is non-normative.
The following shows a very simple manifest .
{
"name": "Donate App",
"description": "This app helps you donate to worthy causes.",
"icons": [{
"src": "images/icon.png",
"sizes": "192x192"
}]
}
The following shows a more typical manifest .
{
"lang": "en",
"dir": "ltr",
"name": "Super Racer 3000",
"description": "The ultimate futuristic racing game from the future!",
"short_name": "Racer3K",
"icons": [{
"src": "icon/lowres.webp",
"sizes": "64x64",
"type": "image/webp"
},{
"src": "icon/lowres.png",
"sizes": "64x64"
}, {
"src": "icon/hd_hi",
"sizes": "128x128"
}],
"scope": "/racer/",
"start_url": "/racer/start.html",
"display": "fullscreen",
"orientation": "landscape",
"theme_color": "aliceblue",
"background_color": "red",
"serviceworker": {
"src": "sw.js",
"scope": "/racer/",
"update_via_cache": "none"
},
"screenshots": [{
"src": "screenshots/in-game-1x.jpg",
"sizes": "640x480",
"type": "image/jpeg"
},{
"src": "screenshots/in-game-2x.jpg",
"sizes": "1280x920",
"type": "image/jpeg"
}]
}
link
element
to
link
to
a
manifest
This section is non-normative.
Example
of
using
a
link
element
to
associate
a
website
with
a
manifest
.
The
example
also
shows
how
to
use
[
HTML
]'s
link
and
meta
elements
to
give
the
web
application
a
fallback
name
and
set
of
icons.
<!doctype>
<html>
<title>Racer 3K</title>
<!-- Startup configuration -->
<link rel="manifest" href="manifest.webmanifest">
<!-- Fallback application metadata for legacy browsers -->
<meta name="application-name" content="Racer3K">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<
link
rel
=
"icon"
sizes
=
"512x512"
href
=
"hi_def.png"
>
A common use case of a manifest is for a user agent to install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. That is, the manifest's members, or their defaults, are in effect on the top-level browsing context . This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.
For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When launched, the manifest is applied by the user agent to the top-level browsing context prior to the start URL being loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.
A
Document
may
either
be
installable
or
not.
The
initial
state
of
a
document
is
not
installable
.
At any time, the user agent MAY perform the steps to determine installability of the document :
Document
's
metadata
to
to
populate
manifest
in
a
user-agent-specific
way
(e.g.,
setting
manifest
.
name
to
the
document
title
)
and
considering
the
document
installable
.
Document
MAY
be
considered
installable
(at
the
user
agent's
discretion;
see
§
2.6
Installability
signals
).
The
application's
name
is
derived
from
either
the
name
member
or
short_name
member
(if
either
is
present)
-
otherwise,
it
is
generated
by
the
user
agent
or
provided
by
the
end-user.
When
either
member
is
missing
from
the
manifest,
a
user
agent
MAY
use
the
name
member
as
a
fallback
for
the
short_name
member
or
vice
versa.
If
the
name
and
short_name
members
are
undefined,
the
user
agent
SHOULD
assign
a
default
name
(e.g.,
"Untitled")
that
follows
platform
conventions.
Alternatively,
a
user
agent
MAY
allow
the
end-user
to
input
some
text
that
can
serve
as
the
application's
name
.
When
both
the
name
and
short_name
members
are
present,
it
is
left
up
to
implementations
to
decide
which
member
is
best
suited
for
the
space
available
(e.g.,
the
short_name
member
might
be
better
suited
for
the
space
available
underneath
an
icon).
An
installation
process
is
an
attempt
by
the
user
agent
to
install
a
web
application.
The
details
of
such
a
process
(i.e.,
the
display
of
an
install
UI
,
and
any
resulting
IO
operations
of
the
host
OS
)
are
left
up
to
implementers.
Implementers
need
to
be
aware
that
there
are
privacy
and
security
considerations
that
directly
relate
to
the
installation
process
.
For
the
purpose
of
this
specification,
the
installation
succeeded
once
the
installation
process
succeeds
in
installing
the
web
application
(e.g.,
an
icon
was
successfully
placed
onto
the
device's
homescreen).
If
the
end-user
cancels
the
installation
process
(even
if
they
manually
triggered
it,
and
then
changed
their
minds),
then
the
installation
was
canceled
.
Otherwise,
the
installation
failed
.
Reasons
for
installation
failure
can
include,
for
example,
the
OS
denying
permission
to
the
user
agent
to
add
an
icon
to
the
homescreen
of
the
device
and
the
end-user
rejecting
the
installation.
The
steps
to
install
the
web
application
are
given
by
the
following
algorithm:
serviceworker
member
with
manifest
returns
a
valid
registration
,
Document
's
relevant
settings
object
,
or
null
if
unavailable.
appinstalled
at
the
Window
object
of
the
top-level
browsing
context
for
which
the
installation
took
place.
Invoke Start Register with scope and src members of the registration, a new promise, client, manifest URL, plus the type and update_via_cache members of the registration, in which case the state of the settled promise determines whether the installation succeeded or not.
There
is
no
"Start
Register"
in
the
SW
spec.
As
far
as
I
can
tell,
the
nearest
thing
would
be
to
simply
invoke
the
register()
method.
I'm also not sure why this method would (ever) have taken the manifest URL. If we can avoid passing the manifest URL, then we don't need to store it in this algorithm.
Also note that this feature doesn't seem to have been implemented by any user agent, so it is considered "at risk" (though I still believe it would be useful which is why I haven't pushed to deleted it yet).
There are multiple ways that the installation process can be triggered:
In any case, the user agent MUST NOT present an install prompt if the document is not installable .
Prior to presenting an automated install prompt , a user agent MUST run the steps to notify that an install prompt is available , to give the site the opportunity to prevent the default action (which is to install the application). Alternatively, the user agent MAY , at any time (only if the document is installable ), run the steps to notify that an install prompt is available at any time, giving the site the opportunity to show a site-triggered install prompt without automatically showing the prompt.
In
either
case,
when
a
user
agent
presents
To
present
an
install
prompt
,
:
accepted
or
dismissed
.
AppBannerPromptOutcome
accepted
The steps to notify that an install prompt is available are given by the following algorithm:
Document
of
the
top-level
browsing
context
is
completely
loaded
.
BeforeInstallPromptEvent
named
beforeinstallprompt
,
with
its
cancelable
attribute
initialized
to
true.
Window
object
of
the
top-level
browsing
context
.
During
the
installation
process
presentation
of
the
install
prompt
,
it
is
RECOMMENDED
that
the
user
agent
allow
the
end-user
to
inspect
the
icon,
name,
start
URL
,
origin,
etc.
pertaining
to
a
web
application.
This
is
to
give
an
end-user
an
opportunity
to
make
a
conscious
decision
to
approve,
and
possibly
modify,
the
information
pertaining
to
the
web
application
before
installing
it.
This
also
gives
the
end-user
an
opportunity
to
discern
if
the
web
application
is
spoofing
another
web
application,
by,
for
example,
using
an
unexpected
icon
or
name.
It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.
This section is non-normative.
By design, this specification does not provide developers with an explicit API to "install" a web application. Instead, a manifest can serve as an installability signal to a user agent that a web application can be installed .
Examples of installability signals for a web application:
name
member
and
a
suitable
icon.
This list is not exhaustive and some installability signals might not apply to all user agents. How a user agent makes use of these installability signals to determine if a web application can be installed is left to implementers.
User agents SHOULD provide a mechanism for the user to remove the installed application.
It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.
DOM events fired by this specification use the application life-cycle task source .
BeforeInstallPromptEvent
Interface
[Exposed=Window] interfaceBeforeInstallPromptEvent
: Event {constructor
(DOMString type, optional EventInit eventInitDict = {}); Promise<PromptResponseObject
>prompt
(); }; dictionaryPromptResponseObject
{AppBannerPromptOutcome
userChoice
; }; enumAppBannerPromptOutcome
{ "accepted
", "dismissed
" };
The
BeforeInstallPromptEvent
is
dispatched
when
the
site
is
allowed
to
present
a
site-triggered
install
prompt
,
or
prior
to
the
user
agent
presenting
an
automated
install
prompt
.
It
allows
the
site
to
cancel
the
automated
install
prompt
,
as
well
as
manually
present
the
site-triggered
install
prompt
.
BeforeInstallPromptEvent
is
not
cancelled,
the
user
agent
is
allowed
to
present
an
install
prompt
(specifically,
an
automated
install
prompt
)
to
the
end-user.
Canceling
the
default
action
(via
preventDefault
)
prevents
the
user
agent
from
presenting
an
The
PromptResponseObject
contains
the
result
of
calling
prompt()
.
It
contains
one
member,
userChoice
,
which
states
the
user's
chosen
outcome.
An
instance
of
a
BeforeInstallPromptEvent
has
the
following
internal
slots:
false
.
Represents
whether
this
event
was
used
to
present
an
install
prompt
to
the
end-user.
prompt()
method
The
prompt
method,
when
called,
runs
the
following
steps:
isTrusted
attribute
is
false
,
reject
this
.
[[userResponsePromise]]
with
NotAllowedError
,
optionally
informing
the
developer
that
untrusted
events
can't
call
prompt()
.
false
,
set
this
.
[[didPrompt]]
to
true
,
then
in
parallel
,
request
to
present
an
install
prompt
with
this
event.
Wait,
possibly
indefinitely,
for
the
end-user
to
make
a
choice.
To
request
to
present
an
install
prompt
with
BeforeInstallPromptEvent
event
:
PromptResponseObject
whose
userChoice
member
is
the
value
of
outcome
.
This section is non-normative.
This example shows how one might prevent an automated install prompt from showing until the user clicks a button to show a site-triggered install prompt . In this way, the site can leave installation at the user's discretion (rather than prompting at an arbitrary time), whilst still providing a prominent UI to do so.
window.addEventListener("beforeinstallprompt", event => {
// Suppress automatic prompting.
event.preventDefault();
// Show the (disabled-by-default) install button. This button
// resolves the installButtonClicked promise when clicked.
installButton.disabled = false;
// Wait for the user to click the button.
installButton.addEventListener("click", async e => {
// The prompt() method can only be used once.
installButton.disabled = true;
// Show the prompt.
const { userChoice } = await event.prompt();
console.info(`user choice was: ${userChoice}`);
});
});
Window
object
The
following
extensions
to
the
Window
object
specify
the
event
handler
attributes
on
which
events
relating
to
the
installation
of
a
web
application
are
fired
.
partial interface Window
{
attribute EventHandler onappinstalled
;
attribute EventHandler onbeforeinstallprompt
;
};
function handleInstalled(ev) {
const date = new Date(ev.timeStamp / 1000);
console.log(`Yay! Our app got installed at ${date.toTimeString()}.`);
}
// Using the event handler IDL attribute
window.onappinstalled = handleInstalled;
// Using .addEventListener()
window
.addEventListener(
"appinstalled"
,
handleInstalled);
onappinstalled
attribute
The
onappinstalled
is
an
event
handler
IDL
attribute
for
the
"
appinstalled
"
event
type.
The
interface
used
for
these
events
is
the
Event
interface
[
DOM
].
This
event
is
dispatched
as
a
result
of
a
successful
installation
(see
the
steps
to
install
the
web
application
).
onbeforeinstallprompt
attribute
The
onbeforeinstallprompt
is
an
event
handler
IDL
attribute
for
the
"
beforeinstallprompt
"
event
type.
The
interface
used
for
these
events
is
the
BeforeInstallPromptEvent
interface
(see
the
steps
to
notify
that
an
install
prompt
is
available
).
A
display
mode
represents
how
the
web
application
is
being
presented
within
the
context
of
an
OS
(e.g.,
in
fullscreen,
etc.).
Display
modes
correspond
to
user
interface
(UI)
(
UI
)
metaphors
and
functionality
in
use
on
a
given
platform.
The
UI
conventions
of
the
display
modes
are
purely
advisory
and
implementers
are
free
to
interpret
them
how
they
best
see
fit.
Once a user agent applies a particular display mode to an application context , it becomes the default display mode for the top-level browsing context (i.e., it is used as the display mode when the window is navigated ). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode .
When
the
display
member
is
missing,
or
if
there
is
no
valid
display
member,
the
user
agent
uses
the
browser
display
mode
as
the
default
display
mode
.
As
such,
the
user
agent
MUST
support
the
browser
display
mode
.
Each
display
mode
,
except
browser
,
has
a
fallback
display
mode
,
which
is
the
display
mode
that
the
user
agent
can
try
to
use
if
it
doesn't
support
a
particular
display
mode
.
If
the
user
agent
does
support
a
fallback
display
mode
,
then
it
checks
to
see
if
it
can
use
that
display
mode
's
fallback
display
mode
.
This
creates
a
fallback
chain,
with
the
default
display
mode
(
browser
)
being
the
last
item
in
the
chain.
For
example,
SuperSecure
Browser
(a
fictitious
browser)
only
supports
the
minimal-ui
and
browser
display
modes,
but
a
developer
declares
that
she
wants
fullscreen
in
the
manifest.
In
this
case,
the
user
agent
will
first
check
if
it
supports
fullscreen
(it
doesn't),
so
it
falls
back
to
standalone
(which
it
also
doesn't
support),
and
ultimately
falls
back
to
minimal-ui
.
The
display
modes
values
defined
by
DisplayModeType
,
and
their
corresponding
fallback
display
modes
are
as
follows:
fullscreen
fullscreen
is
standalone
.
standalone
standalone
is
minimal-ui
.
minimal-ui
standalone
,
but
provides
the
end-user
with
some
means
to
access
a
minimal
set
of
UI
elements
for
controlling
navigation
(i.e.,
back,
forward,
reload,
and
perhaps
some
way
of
viewing
the
document's
address).
A
user
agent
can
include
other
platform
specific
UI
elements,
such
as
"share"
and
"print"
buttons
or
whatever
is
customary
on
the
platform
and
user
agent.
minimal-ui
is
browser
.
browser
browser
display
mode
doesn't
have
a
fallback
display
mode
(conforming
user
agents
are
required
to
support
the
browser
display
mode
).
The
fullscreen
display
mode
is
orthogonal
to,
and
works
independently
of,
the
Fullscreen
API
Standard
.
The
fullscreen
display
mode
affects
the
fullscreen
state
of
the
browser
window,
while
the
[
FULLSCREEN
]
API
operates
on
an
element
contained
within
the
viewport.
As
such,
a
web
application
can
have
its
display
mode
set
to
fullscreen
,
while
document.fullScreenElement
returns
null
,
and
fullscreenEnabled
returns
false
.
When the web application is running, it is RECOMMENDED that the user agent provides the end-user a means to access common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.
Additionally,
when
applying
a
manifest
that
sets
the
display
mode
to
anything
except
"
browser
",
it
is
RECOMMENDED
that
the
user
agent
clearly
indicate
to
the
end-user
that
their
are
leaving
the
normal
browsing
context
of
a
web
browser.
Ideally,
launching
or
switching
to
a
web
application
is
performed
in
a
manner
that
is
consistent
with
launching
or
switching
to
other
applications
in
the
host
platform.
For
example,
a
long
and
obvious
animated
transition,
or
speaking
the
text
"Launching
application
X".
'display-mode'
media
feature
The
display-mode
media
feature
represents,
via
a
CSS
media
query
[
MEDIAQ
],
the
display
mode
of
the
web
application.
This
media
feature
applies
to
the
top-level
browsing
context
and
any
child
browsing
contexts.
Child
browsing
contexts
reflect
the
display
mode
of
the
top-level
browsing
context
.
A
user
agent
MUST
expose
the
'
display-mode
'
media
feature
irrespective
of
whether
a
manifest
is
being
applied
to
a
browsing
context.
For
example,
if
the
end-user
puts
the
whole
user
agent
into
fullscreen,
then
the
user
agent
would
reflect
this
change
to
CSS
and
scripts
via
the
'
display-mode
'
media
feature.
Please
note
that
the
fullscreen
display
mode
is
not
directly
related
to
the
CSS
:fullscreen
pseudo-class
specified
in
the
Fullscreen
API
Standard
.
The
:fullscreen
pseudo-class
matches
exclusively
when
a
[
HTML
]
element
is
put
into
the
fullscreen
element
stack.
However,
a
side
effect
of
calling
the
requestFullscreen()
method
on
an
element
using
the
[
FULLSCREEN
]
API
is
that
the
browser
window
can
enter
a
fullscreen
mode
at
the
OS
-level.
In
such
a
case,
both
:fullscreen
and
(display-mode:
fullscreen)
will
match.
On
some
platforms,
it
is
possible
for
a
user
to
put
a
browser
window
into
fullscreen
without
the
aid
of
the
Fullscreen
API
Standard
.
When
this
happens,
the
:fullscreen
pseudo
class
will
not
match,
but
(display-mode:
fullscreen)
will
match.
This
is
exemplified
in
CSS
code
below.
/* applies when the window is fullscreen */
@media all and (display-mode: fullscreen) {
...
}
/* applies when an element goes fullscreen */
#game:fullscreen {
...
}
fullscreen
|
standalone
|
minimal-ui
|
browser
A user agent MUST reflect the applied display mode of the web application via a CSS media query [ MEDIAQ ].
An example in CSS:
@media all and (display-mode: minimal-ui) {
/* ... */
}
@media all and (display-mode: standalone) {
/* ... */
}
Accessing
the
display-mode
media
feature
in
ECMAScript
through
matchMedia()
of
[
CSSOM-VIEW
]:
const standalone = matchMedia( '(display-mode: standalone)' );
standalone.onchange = (e) => {
/* handle changes to display mode */
}
if (standalone.matches) {
/* do standalone things */
}
The
'display-mode'
media
feature
allows
an
origin
access
to
aspects
of
a
user’s
local
computing
environment
and,
together
with
the
display
member,
allows
an
origin
some
measure
of
control
over
a
user
agent’s
native
UI:
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.
A
resource
is
said
to
be
associated
with
a
manifest
if
the
resource
representation,
an
HTML
document,
has
a
manifest
link
relationship
.
The
manifest
keyword
can
be
used
with
a
[
HTML
]
link
element
.
This
keyword
creates
an
external
resource
link
.
Link type | Effect on... | Brief description | |
---|---|---|---|
link
|
a
and
area
|
||
manifest
|
External Resource | not allowed | Imports or links to a manifest . |
The
media
type
for
a
manifest
serves
as
the
default
media
type
for
resources
associated
with
the
"
manifest
"
link
type
.
In
cases
where
more
than
one
link
element
with
a
manifest
link
type
appears
in
a
Document
,
the
user
agent
uses
the
first
link
element
in
tree
order
and
ignores
all
subsequent
link
element
with
a
manifest
link
type
(even
if
the
first
element
was
erroneous).
See
the
steps
for
obtaining
a
manifest
.
To obtain a manifest, the user agent MUST run the steps for obtaining a manifest . The appropriate time to obtain the manifest is left up to implementations. A user agent MAY opt to delay fetching a manifest until after the document and its other resources have been fully loaded (i.e., to not delay the availability of content and scripts required by the document ).
A
manifest
is
obtained
and
applied
regardless
of
the
media
attribute
of
the
link
element
matches
the
environment
or
not.
This section defines algorithms for obtaining , processing , and applying a manifest .
The steps for obtaining a manifest are given by the following algorithm. The algorithm, if successful, returns a processed manifest and the manifest URL ; otherwise, it terminates prematurely and returns nothing. In the case of nothing being returned, the user agent MUST ignore the manifest declaration. In running these steps, a user agent MUST NOT delay the load event .
Document
of
the
top-level
browsing
context
,
let
origin
be
the
Document
's
origin,
and
manifest
link
be
the
first
link
element
in
tree
order
whose
rel
attribute
contains
the
token
manifest
.
null
,
terminate
this
algorithm.
href
attribute's
value
is
the
empty
string
,
then
abort
these
steps.
href
attribute,
relative
to
the
element's
base
URL
.
If
parsing
fails,
then
abort
these
steps.
manifest
".
crossOrigin
attribute's
value
is
"
use-credentials
",
then
set
request
's
credentials
mode
to
"
include
".
Otherwise,
set
request
's
credentials
mode
to
"
omit
".
cors
".
A user agent MUST support [ CSP3 ].
The
manifest-src
and
default-src
directives
govern
the
origins
from
which
a
user
agent
can
fetch
a
manifest.
As
with
other
directives,
by
default
the
manifest-src
directive
is
*
,
meaning
that
a
user
agent
can,
[
FETCH
]'s
CORS
permitting,
fetch
the
manifest
cross-domain.
Remote
origins
(e.g.,
a
CDN
)
wanting
to
host
manifests
for
various
web
applications
will
need
to
include
the
appropriate
CORS
response
header
in
their
HTTP
response
(e.g.,
Access-Control-Allow-Origin:
https://example.com
).
When instructed to issue a developer warning , the user agent MAY report the conformance violation to the developer in a user-agent-specific manner (e.g., report the problem in an error console), or MAY ignore the error and do nothing.
When instructed to ignore , the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.
The following algorithm provides an extension point : other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm. They SHOULD NOT modify the existing values already in the manifest object.
The extension point is meant to help avoid issues related to monkey patching .
The steps for processing a manifest are given by the following algorithm. The algorithm takes a string text as an argument, which represents a manifest , and a URL manifest URL , which represents the location of the manifest, and a URL document URL . The output from inputting an JSON document into this algorithm is a processed manifest .
We need to catch throws associated with enumerations in IDL conversion as the spec might gain new values over time not supported by all exising browsers. This is especially important as we rely on enums not defined in this specification.
"{}"
.
"{}"
.
WebAppManifest
dictionary.
start_url
"]
to
the
result
of
running
processing
the
start_url
member
given
manifest
["
start_url
"],
manifest
URL
,
and
document
URL
.
lang
"]
to
the
result
of
running
processing
the
lang
member
given
manifest
["
lang
"].
scope
"]
to
the
result
of
running
processing
the
scope
member
given
manifest
["
scope
"],
manifest
URL
,
and
manifest
["
start_url
"].
theme_color
"]
to
the
result
of
running
processing
the
theme_color
member
given
manifest
["
theme_color
"].
background_color
"]
to
the
result
of
running
processing
the
background_color
member
given
manifest
["
background_color
"].
categories
"]
to
the
result
of
running
processing
the
categories
member
given
manifest
["
categories
"].
icons
"]
to
the
result
of
running
processing
ImageResource
members
given
manifest
["
icons
"],
manifest
URL
,
and
"icons"
.
screenshots
"]
to
the
result
of
running
processing
ImageResource
members
given
manifest
["
screenshots
"],
manifest
URL
,
and
"screenshots"
.
related_applications
"]
to
the
result
of
running
processing
the
related_applications
member
given
manifest
["
related_applications
"].
serviceworker
"]
to
the
result
of
running
processing
the
serviceworker
member
given
manifest
["
serviceworker
"],
manifest
URL
,
and
serviceworker
.
A manifest is applied to a top-level browsing context , meaning that the members of the manifest are affecting the presentation or behavior of a browsing context.
A top-level browsing context that has a manifest applied to it is referred to as an application context .
If an application context is created as a result of the user agent being asked to navigate to a deep link , the user agent MUST immediately navigate to the deep link with replacement enabled . Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with replacement enabled .
The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.
Is there a reason that the spec only defines a declarative way to request that a user agent obtain and process a manifest?
Likewise, it would be useful to have an explicit way to request that the user-agent update it's version of the manifest.
WebAppManifest
dictionary
dictionary WebAppManifest
{
TextDirectionType
dir
= "auto";
DOMString lang
;
USVString name
;
USVString short_name
;
USVString description
;
sequence<ImageResource
> icons
;
sequence<ImageResource
> screenshots
;
sequence<USVString> categories
;
DOMString iarc_rating_id
;
USVString start_url
;
DisplayModeType
display
= "browser";
OrientationLockType orientation
;
USVString theme_color
;
USVString background_color
;
USVString scope
;
ServiceWorkerRegistrationObject
serviceworker
;
};
A manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched.
Every manifest has an associated manifest URL , which is the [ URL ] from which the manifest was fetched.
dir
member
enum
TextDirectionType
{
"
ltr
"
,
"
rtl
"
,
"
auto
"
};
The
dir
member
specifies
the
base
direction
for
the
directionality-capable
members
of
the
manifest
.
The
dir
member's
value
can
be
set
to
one
of
the
text-direction
values
.
The directionality-capable members are:
description
member.
name
member.
short_name
member.
The
text-direction
values
defined
by
TextDirectionType
,
are
the
following,
implying
that
the
value
of
the
directionality-capable
members
is
by
default:
ltr
rtl
auto
When
displaying
the
directionality-capable
members
to
an
end-user,
if
the
base
direction
is
ltr
or
rtl
:
ltr
,
or
1
if
the
base
direction
is
rtl
.
ltr
,
or
a
right-to-left
embedding
if
the
base
direction
is
rtl
.
lang
member
The
lang
member
is
a
language
tag
(
string
)
that
specifies
the
primary
language
for
the
values
of
the
manifest's
directionality-capable
members
(as
knowing
the
language
can
also
help
with
directionality).
A
language
tag
is
a
string
that
matches
the
production
of
a
Language-Tag
defined
in
the
[
BCP47
]
specifications
(see
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
of
possible
values).
That
is,
a
language
range
is
composed
of
one
or
more
subtags
that
are
delimited
by
a
U+002D
HYPHEN-MINUS
("-").
For
example,
the
'
en-AU
'
language
range
represents
English
as
spoken
in
Australia,
and
'
fr-CA
'
represents
French
as
spoken
in
Canada.
Language
tags
that
meet
the
validity
criteria
of
[
RFC5646
]
section
2.2.9
that
can
be
verified
without
reference
to
the
IANA
Language
Subtag
Registry
are
considered
structurally
valid.
The
steps
for
processing
the
lang
member
is
given
by
the
following
algorithm.
The
algorithm
takes
a
WebAppManifest
manifest
as
an
argument.
This
algorithm
returns
a
DOMString?
.
false
,
then:
undefined
.
undefined
name
member
The
name
member
is
a
string
that
represents
the
name
of
the
web
application
as
it
is
usually
displayed
to
the
user
(e.g.,
amongst
a
list
of
other
applications,
or
as
a
label
for
an
icon).
short_name
member
The
short_name
member
is
a
string
that
represents
a
short
version
of
the
name
of
the
web
application.
It
is
intended
to
be
used
where
there
is
insufficient
space
to
display
the
full
name
of
the
web
application.
description
member
The
description
member
allows
the
developer
to
describe
the
purpose
of
the
web
application.
scope
member
People
are
confused
by
the
lack
of
examples
relating
to
scope:
pwa-builder/PWABuilder-CLI#42
(comment)
The
scope
member
is
a
string
that
represents
the
navigation
scope
of
this
web
application's
application
context
.
The
steps
for
processing
the
scope
member
is
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
value
,
a
URL
manifest
URL
,
and
a
URL
start
URL
.
This
algorithm
returns
a
URL
.
scope
is
omitted
or
an
error)
is
the
start
URL
,
with
its
filename,
query,
and
fragment
removed.
icons
member
The
icons
member
is
an
array
of
ImageResource
s
that
can
serve
as
iconic
representations
of
the
web
application
in
various
contexts.
For
example,
they
can
be
used
to
represent
the
web
application
amongst
a
list
of
other
applications,
or
to
integrate
the
web
application
with
an
OS
's
task
switcher
and/or
system
preferences.
If
there
are
multiple
equally
appropriate
icons
in
icons
,
a
user
agent
MUST
use
the
last
one
declared
in
order
at
the
time
that
the
user
agent
collected
the
list
of
icons
.
If
the
user
agent
tries
to
use
an
icon
but
that
icon
is
determined,
upon
closer
examination,
to
in
fact
be
inappropriate
(e.g.
because
its
content
type
is
unsupported),
then
the
user
agent
MUST
try
the
next-most-appropriate
icon
as
determined
by
examining
the
ImageResource
's
members.
In the following example, the developer has made the following choices about the icons associated with the web application:
type
member.
If
the
user
agent
doesn't
support
WebP,
it
falls
back
to
the
second
icon
of
the
same
size.
The
media
type
of
this
icon
can
then
be
either
determined
via
a
HTTP
header,
or
can
be
sniffed
by
the
user
agent
once
the
first
few
bytes
of
the
icon
are
received.
{
"icons": [
{
"src": "icon/lowres.webp",
"sizes": "48x48",
"type": "image/webp"
},{
"src": "icon/lowres",
"sizes": "48x48"
},{
"src": "icon/hd_hi.ico",
"sizes": "72x72 96x96 128x128 256x256"
},{
"src": "icon/hd_hi.svg",
"sizes": "257x257"
}]
}
display
member
enum DisplayModeType
{
"fullscreen
",
"standalone
",
"minimal-ui
",
"browser
"
};
The
display
member
is
a
DisplayModeType
,
whose
value
is
one
of
display
modes
values
.
The
item
represents
the
developer's
preferred
display
mode
for
the
web
application.
orientation
member
The
orientation
member
is
a
string
that
serves
as
the
default
orientation
for
all
top-level
browsing
contexts
of
the
web
application.
The
possible
values
are
those
of
the
OrientationLockType
enum
defined
in
[
SCREEN-ORIENTATION
].
If
the
user
agent
honors
the
value
of
the
orientation
member
as
the
default
orientation
,
then
that
serves
as
the
default
orientation
for
the
life
of
the
web
application
(unless
overridden
by
some
other
means
at
runtime).
This
means
that
the
user
agent
MUST
return
the
orientation
to
the
default
orientation
any
time
the
orientation
is
unlocked
[
SCREEN-ORIENTATION
]
or
the
top-level
browsing
context
is
navigated
.
Although the specification relies on the [ SCREEN-ORIENTATION ]'s OrientationLockType , it is OPTIONAL for a user agent to implement the [ SCREEN-ORIENTATION ] API. Supporting the [ SCREEN-ORIENTATION ] API is, of course, RECOMMENDED .
Certain
UI/UX
UI
/UX
concerns
and/or
platform
conventions
will
mean
that
some
screen
orientations
and
display
modes
cannot
be
used
together
.
Which
orientations
and
display
modes
cannot
be
used
together
is
left
to
the
discretion
of
implementers.
For
example,
for
some
user
agents,
it
might
not
make
sense
to
change
the
default
orientation
of
an
application
while
in
browser
display
mode
.
Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [ SCREEN-ORIENTATION ] API).
start_url
member
The
start_url
member
is
a
string
that
represents
the
start
URL
,
which
is
URL
that
the
developer
would
prefer
the
user
agent
load
when
the
user
launches
the
web
application
(e.g.,
when
the
user
clicks
on
the
icon
of
the
web
application
from
a
device's
application
menu
or
homescreen).
The
start_url
member
is
purely
advisory,
and
a
user
agent
MAY
ignore
it
or
provide
the
end-user
the
choice
not
to
make
use
of
it.
A
user
agent
MAY
also
allow
the
end-user
to
modify
the
URL
when,
for
instance,
a
bookmark
for
the
web
application
is
being
created
or
any
time
thereafter.
The
steps
for
processing
the
start_url
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
value
,
a
URL
manifest
URL
,
and
a
URL
document
URL
.
This
algorithm
returns
a
URL
.
start_url
needs
to
be
same-origin
as
the
Document
of
the
top-level
browsing
context
.
For
example,
if
the
value
of
start_url
is
../start_point.html
,
and
the
manifest's
URL
is
https://example.com/resources/manifest.webmanifest
,
then
the
result
of
URL
parsing
would
be
https://example.com/start_point.html
.
start_url
tracking
It's
conceivable
that
the
start_url
could
be
crafted
to
indicate
that
the
application
was
launched
from
outside
the
browser
(e.g.,
"start_url":
"index.html?launcher=homescreen"
).
This
can
be
useful
for
analytics
and
possibly
other
customizations.
However,
it
is
also
conceivable
that
developers
could
encode
strings
into
the
start_url
that
uniquely
identify
the
user
(e.g.,
a
server
assigned
UUID
).
This
is
fingerprinting/privacy
sensitive
information
that
the
user
might
not
be
aware
of.
Given the above, it is RECOMMENDED that, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify the start URL of an application.
serviceworker
member
The
serviceworker
member
describes
a
service
worker
as
defined
in
[
SERVICE-WORKERS-1
].
The
serviceworker
member
represents
an
intented
service
worker
registration
in
form
of
a
registration
object
Other service worker registrations can be done, for instance by a script; if these have different scopes they will be considered separate registrations. If they have the same scope and script URL, they coalesce. If they have different script URLs, last one wins.
The
steps
for
processing
the
serviceworker
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
ServiceWorkerRegistrationObject
registration
.
This
algorithm
returns
a
ServiceWorkerRegistrationObject
registration
,
which
can
be
undefined
.
undefined
,
return
undefined
.
src
member
of
a
service
worker
given
registration
["src"]
and
manifest
URL
.
Not
Trusted
,
issue
a
developer
warning
,
abort
these
steps
and
return
undefined
.
scope
member
of
a
service
worker
given
registration
["scope"].
/foo
scope,
bypassing
the
user
agent
cache
when
fetching
the
"sw.js"
source:
"serviceworker": {
"src": "sw.js",
"scope": "/foo",
"update_via_cache": "none"
}
theme_color
member
The
theme_color
member
serves
as
the
default
theme
color
for
an
application
context.
What
constitutes
a
theme
color
is
defined
in
[
HTML
].
If
the
user
agent
honors
the
value
of
the
theme_color
member
as
the
default
theme
color
,
then
that
color
serves
as
the
theme
color
for
all
browsing
contexts
to
which
the
manifest
is
applied
.
However,
a
document
may
override
the
default
theme
color
through
the
inclusion
of
a
valid
[
HTML
]
meta
element
whose
name
attribute
is
"theme-color".
The
steps
for
processing
the
theme_color
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
theme
color
as
an
argument.
This
algorithm
returns
a
USVString?
.
We currently rely on [[CSS-SYNTAX-3]] "parse a component value", but that's an internal algorithm that's participating in a larger parser... it also skips of preconditions that the parser requires.
undefined
.
undefined
.
background_color
member
The
background_color
member
describes
the
expected
background
color
of
the
web
application.
It
repeats
what
is
already
available
in
the
application
stylesheet
but
can
be
used
by
the
user
agent
to
draw
the
background
color
of
a
web
application
for
which
the
manifest
is
known
before
the
files
are
actually
available,
whether
they
are
fetched
from
the
network
or
retrieved
from
disk.
The
background_color
member
is
only
meant
to
improve
the
user
experience
while
a
web
application
is
loading
and
MUST
NOT
be
used
by
the
user
agent
as
the
background
color
when
the
web
application's
stylesheet
is
available.
The
steps
for
processing
the
background_color
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
background
color
as
an
argument.
This
algorithm
returns
a
USVString?
.
undefined
.
undefined
.
categories
member
The
categories
member
describes
the
expected
application
categories
to
which
the
web
application
belongs.
The
categories
member
is
only
meant
as
a
hint
to
catalogs
or
stores
listing
web
applications
and
it
is
expected
that
these
will
make
a
best
effort
to
find
appropriate
categories
(or
category)
under
which
to
list
the
web
application.
Like
search
engines
and
meta
keywords,
catalogs
and
stores
are
not
required
to
honor
this
hint.
The
steps
for
processing
the
categories
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
sequence<
USVString
>
categories
as
an
argument.
This
algorithm
returns
an
Array<USVString>
.
The
categories
string
array
is
case
insensitive
and
converted
to
lower-case
by
following
the
processing
algorithm.
Thus,
sports
,
Sports
,
SPORTS
,
and
SpOrTs
are
all
equivalent.
Manifest authors are encouraged to use lower-case.
This
specification
does
not
define
the
particular
values
for
USVString
s
for
the
categories
member.
However,
the
working
group
maintains
a
list
of
known
values
in
our
wiki.
screenshots
member
The
screenshots
member
is
an
array
of
ImageResource
s,
representing
the
web
application
in
common
usage
scenarios.
iarc_rating_id
member
The
iarc_rating_id
member
is
a
string
that
represents
the
International
Age
Rating
Coalition
(IARC)
certification
code
of
the
web
application.
It
is
intended
to
be
used
to
determine
which
ages
the
web
application
is
appropriate
for.
An
IARC
certificate
can
be
obtained
via
participating
storefronts,
intended
to
be
used
for
distributing
the
web
app.
The
iarc_rating_id
member
only
takes
a
single
certification
code.
The
same
code
can
be
shared
across
participating
storefronts,
as
long
as
the
distributed
product
remains
the
same
(i.e.,
doesn’t
serve
totally
different
code
paths
depending
on
user
agent
sniffing
and
the
like)
and
the
other
storefronts
support
it.
The
following
shows
a
very
simple
manifest
with
the
iarc_rating_id
member.
{
"name": "Donate App",
"description": "This app helps you donate to worthy causes.",
"iarc_rating_id": "e84b072d-71b3-4d3e-86ae-31a8ce4e53b7",
"icons": [{
"src": "images/icon.png",
"sizes": "192x192"
}]
}
More information on the IARC can be found at: How IARC Works and How developers can get their games and apps rated with IARC .
ImageResource
and
its
members
dictionary ImageResource
{
required USVString src
;
DOMString sizes
;
USVString type
;
USVString purpose
;
USVString platform
;
};
Each
ImageResource
represents
an
image
that
is
used
as
part
of
a
web
application,
suitable
to
use
in
various
contexts
depending
on
the
semantics
of
the
member
that
is
using
the
object
(e.g.,
an
icon
that
is
part
of
an
application
menu,
etc.).
For
an
image
resource,
this
specification
provides
developers
with
a
means
of
specifying
the
dimensions,
and
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.
User
agents
may
modify
the
images
associated
with
an
ImageResource
to
better
match
the
platform’s
visual
style
before
displaying
it
to
the
user,
for
example
by
rounding
the
corners
or
painting
it
in
a
specific
color.
It
is
recommended
that
developers
prepare
their
image
resources
for
such
scenarios
to
avoid
losing
important
information
through,
e.g.,
change
of
color
or
clipped
corners.
To
fetch
the
image
associated
with
an
ImageResource
,
the
user
agent
MUST
run
the
steps
to
fetch
an
image
resource
.
The
algorithm
takes
an
image
URL
(
ImageResource.src
),
the
manifest
URL
,
and
the
Document
document
from
which
the
manifest
was
linked.
It
returns
a
Response
:
The
security
policy
that
governs
whether
a
user
agent
can
fetch
an
icon
image
is
governed
by
the
img-src
directive
[
CSP3
]
associated
with
the
manifest's
owner
Document
.
For
example,
given
the
following
img-src
directive
in
the
Content-Security-Policy
HTTP
header
of
the
manifest's
owner
Document
:
HTTP/1.1 200 OK
Content-Type: text/html
Content-Security-Policy: img-src icons.example.com
<!doctype>
<html>
<
link
rel
=
"manifest"
href
=
"manifest.webmanifest"
>
And
given
the
following
manifest.webmanifest
:
{
"name": "custom manifest",
"start_url": "https://boo",
"icons": [
{
"src": "//icons.example.com/lowres"
},
{
"src": "//other.com/hi-res"
}
]
}
The
fetching
of
icon
resources
from
icons.example.com/lowres
would
succeed,
while
fetching
from
other.com/hi-res
would
fail.
purpose
member
The
purpose
member
is
an
unordered
set
of
unique
space-separated
tokens
that
are
ASCII
case-insensitive
.
The
allowed
values
are
the
icon
purposes
.
When
an
ImageResource
is
used
as
an
icon
,
a
developer
can
hint
that
the
image
is
intended
to
serve
some
special
purpose
in
the
context
of
the
host
OS
(i.e.,
for
better
integration).
User
agents
SHOULD
NOT
use
an
icon
other
than
for
its
stated
purpose
.
For
example,
an
icon
with
purpose
"
badge
"
could
be
used
as
a
badge
or
pinned
icon
that
is
visually
distinct,
in
color
or
form,
from
an
application's
launch
icon.
The
user
agent
uses
the
value
of
the
purpose
member
as
a
hint
to
determine
where
and
how
an
ImageResource
is
displayed.
Unless
declared
otherwise
by
the
developer,
a
user
agent
can
use
an
icon
for
any
purpose
.
The icon purposes are as follows:
If
an
icon
contains
multiple
purposes,
it
could
be
used
for
any
of
those
purposes.
If
none
of
the
stated
purposes
are
recognized,
the
icon
is
totally
ignored.
For
example,
if
an
icon
has
purpose
"badge
fizzbuzz"
,
then
it
could
be
used
as
a
badge,
but
if
an
icon
has
just
the
purpose
"fizzbuzz"
,
then
it
will
be
ignored.
The
steps
for
processing
the
purpose
member
of
an
image
are
given
by
the
following
algorithm.
The
algorithm
takes
an
ImageResource
image
.
This
algorithm
returns
a
set
or
failure.
In the following example, the web application is listing two icons to be used as a badge, one of which is specifically designed for the Android platform.
{
"name": "News",
"icons": [{
"platform": "play",
"purpose": "badge",
"sizes": "16x16",
"src": "icons/badges/android.png",
"type": "image/png"
}, {
"purpose": "badge",
"src": "icons/badges/safari.svg",
"type": "image/svg"
}]
}
Some platforms have their own preferred icon shape, but as web applications should work across multiple platforms, it is possible to indicate that an icon can have a user-agent-specified mask applied by adding the maskable purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different masks and background colors in different places throughout the platform.
The safe zone is the area within a maskable icon which is guaranteed to always be visible, regardless of user agent preferences. It is defined as a circle with center point in the center of the icon and with a radius of 2/5 (40%) of the icon size, which means the smaller of the icon width and height, in case the icon is not square.
Designers of maskable icons will want to make sure that all important parts are within the safe zone .
All pixels in this zone are guaranteed to be seen in all masks. Pixels outside the safe zone are not guaranteed to (but can) be visible depending on the applied mask.
The user agent MAY apply a mask of any size, making any pixels that are more than 2/5ths of the image size (minimum of width and height if non-square) away from the center (the safe zone ) transparent.
The user agent MUST NOT make any pixel within the safe zone transparent.
The user agent MAY enlarge the icon by adding additional padding.
If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid color (eg. white) of the user agent's choice.
It is suggested that designers avoid using transparent pixels in maskable icons.
By staying inside the safe zone , most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.
The
sizes
member
of
an
ImageResource
is
a
string
consisting
of
an
unordered
set
of
unique
space-separated
tokens
which
are
ASCII
case-insensitive
that
represents
the
dimensions
of
an
image.
Each
keyword
is
either
an
ASCII
case-insensitive
match
for
the
string
"
any"
,
or
a
value
that
consists
of
two
valid
non-negative
integers
that
do
not
have
a
leading
U+0030
DIGIT
ZERO
(0)
character
and
that
are
separated
by
a
single
U+0078
LATIN
SMALL
LETTER
X
or
U+0058
LATIN
CAPITAL
LETTER
X
character.
The
keywords
represent
icon
sizes
in
raw
pixels
(as
opposed
to
CSS
pixels).
When
multiple
ImageResource
s
are
available,
a
user
agent
MAY
use
the
value
to
decide
which
icon
is
most
suitable
for
a
display
context
(and
ignore
any
that
are
inappropriate).
The
steps
for
processing
the
sizes
member
of
an
image
are
given
by
the
following
algorithm.
The
algorithm
takes
an
ImageResource
image
.
This
algorithm
will
return
a
set.
src
member
The
src
member
of
an
ImageResource
is
a
URL
from
which
a
user
agent
can
fetch
the
image's
data.
The
steps
for
processing
the
src
member
of
an
image
are
given
by
the
following
algorithm.
The
algorithm
takes
a
ImageResource
icon
,
and
a
URL
manifest
URL
,
which
is
the
URL
from
which
the
manifest
was
fetched.
This
algorithm
will
return
a
URL
or
undefined
.
type
member
The
type
member
of
an
ImageResource
is
a
hint
as
to
the
media
type
of
the
image.
The
purpose
of
this
member
is
to
allow
a
user
agent
to
ignore
images
of
media
types
it
does
not
support.
There is no default MIME type for image resources. However, for the purposes of determining the type of the resource , user agents must expect the resource to be an image.
The
steps
for
processing
the
type
member
of
an
image
are
given
by
the
following
algorithm.
The
algorithm
takes
an
image
object
as
an
argument,
and
returns
either
a
string
or
undefined
.
undefined
.
undefined
.
platform
member
The
platform
member
represents
the
platform
to
which
a
containing
object
applies.
The
steps
for
processing
ImageResource
members
are
given
by
the
following
algorithm.
The
algorithm
takes
a
manifest,
a
URL
manifest
URL
,
which
is
the
URL
from
which
the
manifest
was
fetched,
and
a
string
that
represents
the
member
name
of
the
member
which
contains
the
array
of
ImageResource
s.
This
algorithm
returns
an
Array<
ImageResource
>
undefined
:
src
member
of
an
image
given
entry
and
manifest
URL
.
type
member
of
an
image
given
entry
and
manifest
URL
.
sizes
member
of
an
image
given
entry
and
manifest
URL
.
purpose
member
of
an
image
given
entry
and
manifest
URL
.
This section specifies members that can be used on multiple objects. Each member specifies which object a multi-purpose member can be used with.
platform
member
The
platform
member
represents
the
platform
to
which
a
containing
object
applies.
The following object types can make use of this member:
A
platform
represents
a
software
distribution
ecosystem
or
possibly
an
operating
system.
This
specification
does
not
define
the
particular
values
for
a
the
platform
member.
However,
the
working
group
maintains
a
list
of
known
platform
values
in
our
wiki.
A
ServiceWorkerRegistrationObject
dictionary
represents
a
service
worker
registration
for
the
web
application.
dictionary ServiceWorkerRegistrationObject
{
required USVString src
;
USVString scope
;
WorkerType type
= "classic";
ServiceWorkerUpdateViaCache update_via_cache
= "imports";
};
src
member
The
src
member
of
a
ServiceWorkerRegistrationObject
dictionary
is
a
URL
representing
a
service
worker.
The
steps
for
processing
the
src
member
of
a
service
worker
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
source
URL
,
and
a
URL
manifest
URL
,
which
is
the
URL
from
which
the
manifest
was
fetched.
This
algorithm
will
return
a
URL
or
undefined
.
scope
member
The
scope
member
of
a
ServiceWorkerRegistrationObject
dictionary
is
the
service
worker's
associated
scope
URL
.
The
steps
for
processing
the
scope
member
of
a
service
worker
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
scope
URL
,
and
a
URL
manifest
URL
,
which
is
the
URL
from
which
the
manifest
was
fetched.
This
algorithm
will
return
a
URL
or
undefined
.
undefined
,
return
undefined
type
member
The
type
member
of
a
ServiceWorkerRegistrationObject
dictionary
is
the
service
worker's
WorkerType
.
The
possible
values
are
those
of
the
WorkerType
enum
defined
in
[
HTML
].
update_via_cache
member
The
update_via_cache
member
of
a
ServiceWorkerRegistrationObject
dictionary
determines
the
update
via
cache
mode
for
the
service
worker.
The
possible
values
are
those
of
the
ServiceWorkerUpdateViaCache
enum
defined
in
[
SERVICE-WORKERS-1
].
dictionary ExternalApplicationResource
{
required USVString platform
;
USVString url
;
DOMString id
;
USVString min_version
;
sequence<Fingerprint
> fingerprints
;
};
Each
ExternalApplicationResource
s
represents
an
application
related
to
the
web
application.
An
application
resource
has
the
following
properties:
platform
url
id
min_version
fingerprints
Fingerprint
objects
used
for
verifying
the
application.
A
valid
ExternalApplicationResource
dictionary
MUST
have
platform
and
either
an
url
or
an
id
(or
both).
In the following example, the web application is listing two different related applications, one on Google Play Store and the other one on the iTunes Store. The one on the Google Play Store has an Android package name, a minimum version specifier, and cryptographic fingerprints used for verification, in a Play-Store-specific manner.
{
"related_applications": [
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=com.example.app1",
"id": "com.example.app1",
"min_version": "2",
"fingerprints": [
{
"type": "sha256_cert",
"value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2"
}
]
},
{
"platform": "itunes",
"url": "https://itunes.apple.com/app/example-app1/id123456789"
}
]
}
Where
should
the
platform
expected
value
be
listed?
url
member
The
url
member
of
an
ExternalApplicationResource
dictionary
represents
the
URL
at
which
the
application
can
be
found.
The
steps
for
processing
the
url
member
of
an
application
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
application
URL
.
This
algorithm
will
return
an
URL
or
undefined
.
undefined
,
return
undefined
.
undefined
.
id
member
The
id
member
of
an
ExternalApplicationResource
dictionary
represents
the
id
which
is
used
to
represent
the
application
on
the
platform.
min_version
member
The
min_version
member
of
an
ExternalApplicationResource
dictionary
represents
the
minimum
version
of
the
application
that
is
considered
related
to
this
web
app.
This
version
is
a
string
with
platform-specific
syntax
and
semantics.
fingerprints
member
dictionary Fingerprint
{
USVString type
;
USVString value
;
};
The
fingerprints
member
of
an
ExternalApplicationResource
dictionary
represents
an
array
of
Fingerprint
s.
Each
Fingerprint
s
represents
a
set
of
cryptographic
fingerprints
used
for
verifying
the
application.
A
fingerprint
has
the
following
two
properties:
type
and
value
.
Each
of
these
are
string
s,
but
their
syntax
and
semantics
are
platform-defined.
The following registrations are for community review and will be submitted to the IESG for review, approval, and registration with IANA .
This section contains the required text for MIME media type registration with IANA .
The
media
type
for
a
manifest
is
application/manifest+json
.
If the protocol over which the manifest is transferred supports the [ MIME-TYPES ] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the media type for a manifest .
This specification does not directly deal with high-value data. However, installed web applications and their data could be seen as "high value" (particularly from a privacy perspective).
As the manifest format is JSON and will commonly be encoded using [ UNICODE ], the security considerations described in [ ECMA-404 ] and [ UNICODE-SECURITY ] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest , implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [ CSS-MIME ], [ ECMAScript-MIME ], [ HTML ].
As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.
As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [ URL ] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [ UNICODE-SECURITY ].
Developers
need
to
be
aware
of
the
security
considerations
discussed
throughout
the
[
CSP3
]
specification,
particularly
in
relation
to
making
data:
a
valid
source
for
the
purpose
of
inlining
a
manifest.
Doing
so
can
enable
XSS
attacks
by
allowing
a
manifest
to
be
included
directly
in
the
document
itself;
this
is
best
avoided
completely.
A
request
to
register
the
manifest
link
relation
type
been
submitted
to
IANA.
This document reuses text from the [ HTML ] specification, as permitted by the license of that specification.
Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.
Claudio Gomboli for icon example images.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , OPTIONAL , RECOMMENDED , SHOULD , and SHOULD NOT in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
There is only one class of product that can claim conformance to this specification: a user agent .
Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.
This section is non-normative.
This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the extension point to hook into the steps for processing a manifest . Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.
To allow the community can easily find extensions, please add your extensions to the Extensions Registry .
When specifying a new member, don't override or monkey patch anything defined in this specification. Also, don't assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.
If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.
This section is non-normative.
Although proprietary extensions are undesirable, they can't realistically be avoided. As such, the RECOMMENDED way to add a new proprietary manifest member as an extension is to use a vendor prefix.
We encourage implementors to add proprietary extensions to our Extensions Registry . This allows the community to track what extensions vendors and/or the web community have defined and documented. Periodically, we will consider those extensions for standardization.
The following is an example of three hypothetical vendor extensions.
{
...
"webkit_fancy_feature": "some/url/img",
"moz_awesome_thing": { ... },
"vendor_example_site_verification": "KEY_9864D0966935"
...
}
link
and
meta
elements
An
extensive
discussion
of
why
we
chose
to
use
JSON
instead
of
HTML
meta
/
link
tags
for
this
specification
is
available
on
GitHub
and
on
the
www-tag
list.
Below
is
a
short
summary
of
the
key
points
raised
in
those
discussions.
The
document
format
defined
in
this
specification
provides
a
unified
means
of
encapsulating
metadata
about
a
Web
application
in
a
way
that
we
hope
will
avoid
existing
pitfalls
with
both
proprietary
and
[
HTML
]'s
meta
/
link
tags.
Those
pitfalls
include:
Although it would be unrealistic to think that this specification won't bring its own set of problems, externalizing this data in the form of a manifest solves the problems described above. These problems are solved by:
meta
tags
are
currently
using,
especially
when
a
tag's
value
contains
several
sub-values.
In
addition,
standardizing
the
functionality
currently
provided
by
the
various
meta
tag-based
solutions
within
the
manifest
solves
the
problem
of
having
to
declare
large
number
of
proprietary
and
standard
[
HTML
]
tags
that
all
achieve
the
same
thing.
Of
course,
this
hinges
on
the
standard
actually
getting
implemented
by
browsers
and
those
browsers
getting
widely
deployed
to
users:
if
this
happens,
the
Web
community
might
be
able
to
retire
many
of
the
proprietary
meta
tags
plaguing
the
Web
at
the
time
of
writing.
More
information
about
the
proprietary
tags
can
be
found
in
the
Use
Cases
and
Requirements
for
Installable
Web
Apps
.
Lastly,
this
specification
does
not
make
the
standardized
solutions
found
in
[
HTML
]
redundant.
When
members
like
the
name
or
icons
is
missing
from
the
manifest,
user
agents
can
search
in
a
manifest's
owner
[
HTML
]
document
for
things
like
icons
and
the
application
name
(or
a
user
agent
might
even
fallback
to
proprietary
tags/metadata,
if
they
are
present
in
a
document).
Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org . It is licensed under Apache 2.0 . It is kindly maintained by Mads Kristensen . If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.
It is expected that authors will localize the content of a manifest by using one of the following options:
Accept-Language
"
header,
or
even
a
custom
HTTP
header).
Given the options above, developers need to be mindful of the end-user's privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user's preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [ TLS ] to reduce the chances of pervasive monitoring of their Web applications [ RFC7258 ].
This document attempts to address the Use Cases and Requirements for Installable Web Apps .
[Exposed=Window] interfaceBeforeInstallPromptEvent
: Event {constructor
(DOMString type, optional EventInit eventInitDict = {}); Promise<PromptResponseObject
>prompt
(); }; dictionaryPromptResponseObject
{AppBannerPromptOutcome
userChoice
; }; enumAppBannerPromptOutcome
{ "accepted
", "dismissed
" }; partial interfaceWindow
{ attribute EventHandleronappinstalled
; attribute EventHandleronbeforeinstallprompt
; }; dictionaryWebAppManifest
{TextDirectionType
dir
= "auto"; DOMStringlang
; USVStringname
; USVStringshort_name
; USVStringdescription
; sequence<ImageResource
>icons
; sequence<ImageResource
>screenshots
; sequence<USVString>categories
; DOMStringiarc_rating_id
; USVStringstart_url
;DisplayModeType
display
= "browser"; OrientationLockTypeorientation
; USVStringtheme_color
; USVStringbackground_color
; USVStringscope
;ServiceWorkerRegistrationObject
serviceworker
; sequence<ExternalApplicationResource
>related_applications
; booleanprefer_related_applications
= "false"; }; enumTextDirectionType
{ "ltr
", "rtl
", "auto
" }; enumDisplayModeType
{ "fullscreen
", "standalone
", "minimal-ui
", "browser
" }; dictionaryImageResource
{ required USVStringsrc
; DOMStringsizes
; USVStringtype
; USVStringpurpose
; USVStringplatform
; }; dictionaryServiceWorkerRegistrationObject
{ required USVStringsrc
; USVStringscope
; WorkerTypetype
= "classic"; ServiceWorkerUpdateViaCacheupdate_via_cache
= "imports"; }; dictionaryExternalApplicationResource
{ required USVStringplatform
; USVStringurl
; DOMStringid
; USVStringmin_version
; sequence<Fingerprint
>fingerprints
; }; dictionaryFingerprint
{ USVStringtype
; USVStringvalue
; };
As
the
manifest
uses
the
JSON
format,
this
specification
relies
on
the
types
defined
in
[
ECMA-404
]
specification:
namely
object
,
array
,
number
,
string
,
true
,
false
,
and
undefined
.
Strict
type
checking
is
not
enforced
by
this
specification.
Instead,
each
member's
definition
specifies
the
steps
required
to
process
a
particular
member
and
what
to
do
when
a
type
does
not
match
what
is
expected.
link
element
rel
attribute
a
element
meta
element
area
element
name
attribute
title
element