Copyright © 2020 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 screen orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to "scope" a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to "deep link" into a web application from other applications.
Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.
This
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 an Editor's Draft.
GitHub Issues are preferred for discussion of this specification.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 March 2019 W3C Process Document .
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",
"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"
>
.webmanifest
.
Some
web
servers
recognize
this
extension
and
transfer
the
file
using
the
standardized
application
manifest
MIME
type
(
application/manifest+json
).
Developers
can
also
choose
a
different
extension
(e.g.
.json
)
or
none
at
all
(e.g.
/api/GetManifest
),
but
are
strongly
encouraged
to
transfer
the
manifest
using
the
application/manifest+json
MIME
type
.
A common use case of a manifest is for a user agent to install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. A web application that is installed is known as a installed web application . That is, the manifest's members, or their defaults, are in effect on the top-level browsing context . This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.
For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When 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
populate
manifest
in
a
user-agent-specific
way
(e.g.,
setting
manifest
.
name
to
the
document
title
and
considering
the
document
installable
.
Document
installable
(see
§
2.4
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).
It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL , origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.
It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.
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 an installed web application application.
It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.
A display mode represents how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.). Display modes correspond to user interface (UI) metaphors and functionality in use on a given platform. The UI conventions of the display modes are purely advisory and implementers are free to interpret them how they best see fit.
Once a user agent applies a particular display mode to an application context , it becomes the default display mode for the top-level browsing context (i.e., it is used as the display mode when the window is navigated ). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode .
When
the
display
member
is
missing,
or
if
there
is
no
valid
display
member,
the
user
agent
uses
the
browser
display
mode
as
the
default
display
mode
.
As
such,
the
user
agent
MUST
support
the
browser
display
mode
.
Each
display
mode
,
except
browser
,
has
a
fallback
display
mode
,
which
is
the
display
mode
that
the
user
agent
can
try
to
use
if
it
doesn't
support
a
particular
display
mode
.
If
the
user
agent
does
support
a
fallback
display
mode
,
then
it
checks
to
see
if
it
can
use
that
display
mode
's
fallback
display
mode
.
This
creates
a
fallback
chain,
with
the
default
display
mode
(
browser
)
being
the
last
item
in
the
chain.
For
example,
SuperSecure
Browser
(a
fictitious
browser)
only
supports
the
minimal-ui
and
browser
display
modes,
but
a
developer
declares
that
she
wants
fullscreen
in
the
manifest.
In
this
case,
the
user
agent
will
first
check
if
it
supports
fullscreen
(it
doesn't),
so
it
falls
back
to
standalone
(which
it
also
doesn't
support),
and
ultimately
falls
back
to
minimal-ui
.
The
display
modes
values
defined
by
DisplayModeType
,
and
their
corresponding
fallback
display
modes
are
as
follows:
fullscreen
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:
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 Link | not allowed | Imports or links to a manifest . |
The
application
manifest
MIME
type
serves
as
the
default
MIME
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
elements
with
a
manifest
link
type
(even
if
the
first
element
was
erroneous).
See
the
steps
for
obtaining
a
manifest
.
To obtain a manifest, the user agent MUST run the steps for obtaining a manifest . The appropriate time to obtain the manifest is left up to implementations. A user agent MAY opt to delay fetching a manifest until after the document and its other resources have been fully loaded (i.e., to not delay the availability of content and scripts required by the document ).
A
manifest
is
obtained
and
applied
regardless
of
the
media
attribute
of
the
link
element
matches
the
environment
or
not.
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 aborts prematurely and returns nothing. In the case of nothing being returned, the user agent MUST ignore the manifest declaration. In running these steps, a user agent MUST NOT delay the load event .
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
,
then
abort
these
steps.
href
attribute's
value
is
the
empty
string
,
then
abort
these
steps.
href
attribute,
relative
to
the
document
base
URL
.
If
parsing
fails,
then
abort
these
steps.
manifest
".
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 existing 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
a
color
member
given
manifest
["
theme_color
"].
background_color
"]
to
the
result
of
running
processing
a
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
ManifestImageResource
members
given
manifest
["
icons
"]
and
manifest
URL
.
screenshots
"]
to
the
result
of
running
processing
ManifestImageResource
members
given
manifest
["
screenshots
"]
and
manifest
URL
.
related_applications
"]
to
the
result
of
running
processing
the
related_applications
member
given
manifest
["
related_applications
"].
shortcuts
"]
to
the
result
of
running
processing
the
shortcuts
member
given
manifest
["
shortcuts
"]
and
manifest
URL
.
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.
The
steps
for
processing
a
color
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
USVString
potential
color
as
an
argument.
This
algorithm
returns
a
USVString
or
undefined
.
undefined
.
undefined
.
Only
sRGB
colors,
and
colors
the
user
agent
can
convert
to
sRGB
without
any
outside
knowledge,
are
supported.
For
example,
lab(…)
or
color(display-p3,
…)
can
be
converted
to
sRGB
without
outside
knowledge,
but
color(--custom-profile,
…)
would
require
finding
a
matching
"@color-profile"
rule
which
cannot
be
specified
in
the
manifest.
WebAppManifest
dictionary
WebIDLdictionaryWebAppManifest
{TextDirectionType
dir
= "auto"; DOMStringlang
; USVStringname
; USVStringshort_name
; USVStringdescription
; sequence<ManifestImageResource
>icons
; sequence<ManifestImageResource
>screenshots
; sequence<USVString>categories
; DOMStringiarc_rating_id
; USVStringstart_url
;DisplayModeType
display
= "browser"; OrientationLockTypeorientation
; USVStringtheme_color
; USVStringbackground_color
; USVStringscope
; sequence<ShortcutItem
>shortcuts
; };
A manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched.
Every manifest has an associated manifest URL , which is the [ URL ] from which the manifest was fetched.
dir
member
WebIDL enumTextDirectionType
{ "ltr
" , "rtl
" , "auto
" };
The
dir
member
specifies
the
base
direction
for
the
localizable
members
of
the
manifest
.
The
dir
member's
value
can
be
set
to
one
of
the
text-direction
values
.
The localizable members are:
description
member.
name
member.
short_name
member.
ShortcutItem
's
name
member.
ShortcutItem
's
short_name
member.
ShortcutItem
's
description
member.
The
text-direction
values
defined
by
TextDirectionType
,
are
the
following,
implying
that
the
value
of
the
localizable
members
is
by
default:
ltr
rtl
auto
When
displaying
the
localizable
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
localizable
members
(as
knowing
the
language
can
also
help
with
directionality).
A
language
tag
is
a
string
that
matches
the
production
of
a
Language-Tag
defined
in
the
[
BCP47
]
specifications
(see
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
of
possible
values).
That
is,
a
language
range
is
composed
of
one
or
more
subtags
that
are
delimited
by
a
U+002D
HYPHEN-MINUS
("-").
For
example,
the
'
en-AU
'
language
range
represents
English
as
spoken
in
Australia,
and
'
fr-CA
'
represents
French
as
spoken
in
Canada.
Language
tags
that
meet
the
validity
criteria
of
[
RFC5646
]
section
2.2.9
that
can
be
verified
without
reference
to
the
IANA
Language
Subtag
Registry
are
considered
structurally
valid.
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
are
images
that
serve
as
iconic
representations
of
the
web
application
in
various
contexts.
For
example,
they
can
be
used
to
represent
the
web
application
amongst
a
list
of
other
applications,
or
to
integrate
the
web
application
with
an
OS
's
task
switcher
and/or
system
preferences.
If
there
are
multiple
equally
appropriate
images
in
,
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
icons
's
members.
ManifestImageResource
In the following example, the developer has made the following choices about the icons associated with the web application:
type
member.
If
the
user
agent
doesn't
support
WebP,
it
falls
back
to
the
second
icon
of
the
same
size.
The
MIME
type
of
this
icon
can
then
be
either
determined
via
a
HTTP
header,
or
can
be
sniffed
by
the
user
agent
once
the
first
few
bytes
of
the
icon
are
received.
{
"icons": [
{
"src": "icon/lowres.webp",
"sizes": "48x48",
"type": "image/webp"
},{
"src": "icon/lowres",
"sizes": "48x48"
},{
"src": "icon/hd_hi.ico",
"sizes": "72x72 96x96 128x128 256x256"
},{
"src": "icon/hd_hi.svg",
"sizes": "257x257"
}]
}
display
member
WebIDLenumDisplayModeType
{ "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
screen
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
screen
orientation
,
then
that
serves
as
the
default
screen
orientation
for
the
life
of
the
web
application
(unless
overridden
by
some
other
means
at
runtime).
This
means
that
the
user
agent
MUST
return
the
orientation
to
the
default
screen
orientation
any
time
the
orientation
is
unlocked
[
SCREEN-ORIENTATION
]
or
the
top-level
browsing
context
is
navigated
.
Although
the
specification
relies
on
the
[
SCREEN-ORIENTATION
]'s
OrientationLockType
,
it
is
OPTIONAL
for
a
user
agent
to
implement
the
[
SCREEN-ORIENTATION
]
API.
Supporting
the
[
SCREEN-ORIENTATION
]
API
is,
of
course,
RECOMMENDED
.
Certain
UI/UX
concerns
and/or
platform
conventions
will
mean
that
some
screen
orientations
and
display
modes
cannot
be
used
together
.
Which
orientations
and
display
modes
cannot
be
used
together
is
left
to
the
discretion
of
implementers.
For
example,
for
some
user
agents,
it
might
not
make
sense
to
change
the
default
screen
orientation
of
an
application
while
in
browser
display
mode
.
Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [ SCREEN-ORIENTATION ] API).
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
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.
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 user agent MAY ignore the theme color 's alpha component based on the context. For example, in most environments, the theme color cannot be transparent.
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.
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
s,
representing
the
web
application
in
common
usage
scenarios.
ManifestImageResource
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 .
shortcuts
member
The
shortcuts
member
is
an
array
of
ShortcutItem
s
that
provide
access
to
key
tasks
within
a
web
application.
Shortcuts could, for instance, be used to link directly to a user's timeline within a social media application or to their recent orders in an e-commerce context.
How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.
Developers are encouraged to order their shortcuts by priority, with the most critical shortcuts appearing first in the array.
The
steps
for
processing
the
shortcuts
member
are
given
by
the
following
algorithm.
The
algorithm
takes
a
sequence
<
ShortcutItem
>
shortcuts
and
a
URL
manifest
URL
.
This
algorithm
returns
a
sequence
<
ShortcutItem
>.
ShortcutItem
)
in
the
sequence:
ManifestImageResource
members
given
shortcut
["icons"]
and
manifest
URL
.
A user agent SHOULD expose shortcuts via interactions that are consistent with exposure of an application icon's context menu in the host operating system (e.g., right click, long press). A user agent SHOULD render the shortcuts in the same order as they are provided in the manifest. A user agent SHOULD represent the shortcuts in a manner consistent with exposure of an application icon's context menu in the host operating system. A user agent MAY truncate the list of shortcuts presented in order to remain consistent with the conventions or limitations of the host operating system.
In the following example, the developer has included two shortcuts. Assuming the the manifest's URL is https://example.com/manifest.webmanifest :
{
"shortcuts": [
{
"name": "Play Later",
"description": "View the list of podcasts you saved for later",
"url": "/play-later",
"icons": [
{
"src": "/icons/play-later.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
},
{
"name": "Subscriptions",
"description": "View the list of podcasts you listen to",
"url": "/subscriptions?sort=desc"
}
]
}
ManifestImageResource
and
its
members
WebIDLdictionaryManifestImageResource
: ImageResource { USVStringplatform
; USVStringpurpose
; };
Each
is
an
image
that
is
conceptually
part
of
a
web
application,
suitable
to
use
in
various
contexts
depending
on
the
semantics
of
the
member
that
is
using
the
object
(e.g.,
an
icon
that
is
part
of
an
application
menu,
etc.).
ManifestImageResource
User
agents
MAY
modify
the
images
associated
with
an
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.
ManifestImageResource
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.
platform
member
The
member
represents
the
platform
to
which
a
containing
object
applies.
platform
purpose
member
The
member
is
an
unordered
set
of
unique
space-separated
tokens
that
are
ASCII
case-insensitive
.
The
allowed
values
are
the
icon
purposes
.
purpose
When
a
is
used
as
an
icon
,
a
developer
can
hint
that
the
image
is
intended
to
serve
some
special
purpose
in
the
context
of
the
host
OS
(i.e.,
for
better
integration).
User
agents
SHOULD
NOT
use
an
icon
other
than
for
its
stated
icon
purpose
.
ManifestImageResource
For
example,
an
icon
with
purpose
"
badge
monochrome
"
could
be
used
as
a
badge
or
pinned
icon
that
is
with
a
solid
fill,
visually
distinct,
in
color
or
form,
distinct
from
an
application's
full
color
launch
icon.
The
user
agent
uses
the
value
of
the
member
as
a
hint
to
determine
where
and
how
purpose
a
an
is
displayed.
Unless
declared
otherwise
by
the
developer,
a
user
agent
can
use
an
icon
for
any
purpose
.
ManifestImageResource
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
,
then
it
could
be
used
as
a
"badge
"monochrome
fizzbuzz"
badge,
but
monochrome
icon,
as
"monochrome"
is
a
valid
purpose.
However,
if
an
icon
has
just
has
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
a
image
.
This
algorithm
returns
a
set
or
failure.
ManifestImageResource
In
the
following
example,
the
web
application
is
listing
two
icons
to
be
used
as
a
badge,
monochrome
icon,
one
of
which
is
specifically
designed
for
the
Android
platform.
{
"name": "News",
"icons": [{
"platform": "play",
,
"purpose": "monochrome",
"sizes": "16x16",
"src": "icons/badges/android.png",
"type": "image/png"
}, {
,
"purpose": "monochrome",
"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.
fill
(e.g.,
white)
of
the
user
agent's
choice.
It is suggested that designers avoid using transparent pixels in maskable icons.
By staying inside the safe zone , most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.
Some platforms enforce that icons be displayed with a solid fill such as a single color, where only the transparency of the icon can be declared in a manifest . As web applications need to work across multiple platforms, it is possible to indicate that an icon can have an user-agent-specified color applied by adding the monochrome purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different colors and padding in different places throughout the platform.
When processing a monochrome icon, the user agent MUST NOT independently display the red component, green component, or blue component of a pixel. The user agent SHOULD display each pixel with its original alpha value, but with a red, green, and blue value of the user agent's choosing. It is RECOMMENDED that the user agent use the same color value for all pixels.
Designers of monochrome icons could set all pixels to black and only use transparency to create a silhouette of their icon.
The user agent MAY enlarge the icon by adding additional padding.
The user agent MAY add a background of any color behind transparent pixels, and SHOULD ensure that the background has sufficient contrast with the icon.
The
steps
for
processing
ManifestImageResource
members
are
given
by
the
following
algorithm.
The
algorithm
takes
an
a
list
of
entries
and
a
URL
manifestURL
.
This
algorithm
returns
an
a
list
of
s.
ManifestImageResource
purpose
member
of
an
image
given
entry
.
ShortcutItem
and
its
members
WebIDLdictionaryShortcutItem
{ required USVStringname
; USVStringshort_name
; USVStringdescription
; required USVStringurl
;sequence<ManifestImageResource
>icons
; };
Each
ShortcutItem
represents
a
link
to
a
key
task
or
page
within
a
web
app.
A
user
agent
can
use
these
values
to
assemble
a
context
menu
to
be
displayed
by
the
operating
system
when
a
user
engages
with
the
web
app's
icon.
When
the
user
invokes
a
shortcut
from
the
operating
system
menu,
the
user
agent
SHOULD
run
Launching
a
shortcut
.
name
member
The
name
member
of
a
ShortcutItem
is
a
string
that
represents
the
name
of
the
shortcut
as
it
is
usually
displayed
to
the
user
in
a
context
menu.
short_name
member
The
short_name
member
of
a
ShortcutItem
is
a
string
that
represents
a
short
version
of
the
name
of
the
shortcut.
It
is
intended
to
be
used
where
there
is
insufficient
space
to
display
the
full
name
of
the
shortcut.
description
member
The
description
member
of
a
ShortcutItem
is
a
string
that
allows
the
developer
to
describe
the
purpose
of
the
shortcut.
User
agents
MAY
expose
this
information
to
assistive
technology.
url
member
The
url
member
of
a
ShortcutItem
is
the
URL
within
the
application's
scope
that
opens
when
the
associated
shortcut
is
activated.
icons
member
The
icons
member
of
an
ShortcutItem
member
serve
as
iconic
representations
of
the
shortcut
in
various
contexts.
When
ShortcutItem
shortcut
having
WebAppManifest
manifest
is
invoked,
run
the
following
steps:
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.
WebIDLdictionaryExternalApplicationResource
{ required USVStringplatform
; USVStringurl
; DOMStringid
; USVStringmin_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
WebIDLdictionaryFingerprint
{ USVStringtype
; USVStringvalue
; };
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
application
manifest
MIME
type
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 application manifest MIME type .
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.
Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.
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"
...
}
Extensions to this specification are being incubated in parallel by the Web Community, some of which are shipping in multiple browsers. If two or more browser engines end up supporting an incubated feature, then those features will become part of this specification in the future - allowing them to become a standard the Web Platform:
BeforeInstallPrompt
and
window.onappinstalled
event
BeforeInstallPrompt
event
and
window.onappinstalled
event
were
originally
part
of
this
specification.
However,
they
were
removed
from
the
specification
because
they
did
not
have
support
from
two
or
more
implementers.
You
can
now
find
them
in
the
BeforeInstallPrompt
event
and
window.onappinstalled
repository
at
the
WICG
.
share_target
member
share_target
member
registers
a
web
application
as
"target"
for
share
actions
(e.g.,
for
sharing
a
text,
a
URL,
or
a
file).
The
share_target
member
is
part
of
the
Web
Share
Target
specification,
being
incubated
at
the
WICG
.
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.
This section is non-normative.
It is expected that authors will localize the content of a manifest by using one of the following options:
Accept-Language
"
header,
or
even
a
custom
HTTP
header).
Given the options above, developers need to be mindful of the end-user's privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user's preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [ TLS ] to reduce the chances of pervasive monitoring of their Web applications [ RFC7258 ].
This document attempts to address the Use Cases and Requirements for Installable Web Apps .
WebIDLdictionaryWebAppManifest
{TextDirectionType
dir
= "auto"; DOMStringlang
; USVStringname
; USVStringshort_name
; USVStringdescription
;sequence<ManifestImageResource
>icons
; sequence<ManifestImageResource
>screenshots
; sequence<USVString>categories
; DOMStringiarc_rating_id
; USVStringstart_url
;DisplayModeType
display
= "browser"; OrientationLockTypeorientation
; USVStringtheme_color
; USVStringbackground_color
; USVStringscope
; sequence<ExternalApplicationResource
>related_applications
; booleanprefer_related_applications
= "false"; sequence<ShortcutItem
>shortcuts
; }; enumTextDirectionType
{ "ltr
", "rtl
", "auto
" }; enumDisplayModeType
{ "fullscreen
", "standalone
", "minimal-ui
", "browser
" }; dictionaryManifestImageResource
: ImageResource { USVStringplatform
;USVStringpurpose
; }; dictionaryShortcutItem
{ required USVStringname
; USVStringshort_name
; USVStringdescription
; required USVStringurl
;sequence<ManifestImageResource
>icons
; }; 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.
"auto"
enum
value
for
TextDirectionType
§8.1
background_color
member
for
WebAppManifest
§8.14
"browser"
enum
value
for
DisplayModeType
§4.
categories
member
for
WebAppManifest
§8.15
WebAppManifest
§8.5
ShortcutItem
§10.3
dir
member
for
WebAppManifest
§8.1
display
member
for
WebAppManifest
§8.8
display-mode
§4.2
DisplayModeType
enum
§4.
ExternalApplicationResource
dictionary
§12.
Fingerprint
dictionary
§12.4
fingerprints
member
for
ExternalApplicationResource
§12.4
"fullscreen"
enum
value
for
DisplayModeType
§4.
iarc_rating_id
member
for
WebAppManifest
§8.17
WebAppManifest
§8.7
ShortcutItem
§10.5
id
member
for
ExternalApplicationResource
§12.2
lang
member
for
WebAppManifest
§8.2
"ltr"
enum
value
for
TextDirectionType
§8.1
ManifestImageResource
dictionary
§9.
min_version
member
for
ExternalApplicationResource
§12.3
"minimal-ui"
enum
value
for
DisplayModeType
§4.
WebAppManifest
§8.3
ShortcutItem
§10.1
orientation
member
for
WebAppManifest
§8.9
prefer_related_applications
member
for
WebAppManifest
§8.13
purpose
member
for
ManifestImageResource
§9.3
related_applications
member
for
WebAppManifest
§8.12
"rtl"
enum
value
for
TextDirectionType
§8.1
scope
member
for
WebAppManifest
§8.6
screenshots
member
for
WebAppManifest
§8.16
WebAppManifest
§8.4
ShortcutItem
§10.2
ShortcutItem
dictionary
§10.
shortcuts
member
for
WebAppManifest
§8.18
"standalone"
enum
value
for
DisplayModeType
§4.
start_url
member
for
WebAppManifest
§8.10
TextDirectionType
enum
§8.1
theme_color
member
for
WebAppManifest
§8.11
type
member
for
Fingerprint
§12.4
value
member
for
Fingerprint
§12.4
WebAppManifest
dictionary
§8.
CSS
)
Document
interface
Document
)
request
)
request
)
request
)
request
)
request
)
a
element
area
element
crossOrigin
attribute
(for
HTMLLinkElement
)
link
element
media
attribute
(for
HTMLLinkElement
)
meta
element
rel
attribute
(for
HTMLLinkElement
)
title
element
ImageResource
list
)
set
)
string
)
list
)
iteration
)
list
)
list
)
set
)
OrientationLockType
enum
boolean
type
DOMString
interface