Copyright © 2021 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
This specification defines a JSON-based file format that provides developers with a centralized place to put metadata associated with a web application. This metadata includes, but is not limited to, the web application's name, links to icons, as well as the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default screen orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to "scope" a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to "deep link" into a web application from other applications.
Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.
This section describes the status of this document at the time of its publication. 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/.
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 15 September 2020 W3C Process Document .
A application manifest is a [ JSON ] document that contains startup parameters and application defaults for when a web application is launched.
As a manifest is JSON, this specification relies on the types defined in [ JSON ] specification: namely object , array , string , and boolean . 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.
A manifest has an associated manifest URL , which is the [ URL ] from which the manifest was fetched.
A manifest can have any of the following members at its root, all of which are optional. The members can appear in any order.
background_color
dir
display
icons
lang
name
orientation
prefer_related_applications
protocol_handlers
related_applications
scope
short_name
shortcuts
start_url
theme_color
This section is non-normative.
This section shows how developers can make use of the various features of this specification.
This section is non-normative.
The following shows a typical manifest .
{
"lang": "en",
"dir": "ltr",
"name": "Super Racer 3000",
"short_name": "Racer3K",
"icons": [{
"src": "icon/lowres.webp",
"sizes": "64x64",
"type": "image/webp"
}, {
"src": "icon/lowres.png",
"sizes": "64x64"
}, {
"src": "icon/hd_hi",
"sizes": "128x128"
}],
"scope": "/",
"start_url": "/start.html",
"display": "fullscreen",
"orientation": "landscape",
"theme_color": "aliceblue",
"background_color": "red"
}
link
element
to
link
to
a
manifest
This section is non-normative.
The
example
also
shows
how
to
use
the
link
type
"manifest"
and
how
to
use
other
meta
and
link
elements
to
give
the
web
application
a
fallback
name
and
set
of
icons.
<!doctype>
<html>
<title>Racer 3K</title>
<!-- Startup configuration -->
<link rel="manifest" href="manifest.webmanifest">
<!-- Fallback application metadata for legacy browsers -->
<meta name="application-name" content="Racer3K">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<
link
rel
=
"icon"
sizes
=
"512x512"
href
=
"hi_def.png"
>
This section is non-normative.
In the following example, the developer has made the following choices about the icons associated with the web application:
type
member.
If
the
user
agent
doesn't
support
WebP,
it
falls
back
to
the
second
icon
of
the
same
size.
The
MIME
type
of
this
icon
can
then
be
either
determined
via
a
HTTP
header,
or
can
be
sniffed
by
the
user
agent
once
the
first
few
bytes
of
the
icon
are
received.
{
"icons": [
{
"src": "icon/lowres.webp",
"sizes": "48x48",
"type": "image/webp"
},{
"src": "icon/lowres",
"sizes": "48x48"
},{
"src": "icon/hd_hi.ico",
"sizes": "72x72 96x96 128x128 256x256"
},{
"src": "icon/hd_hi.svg",
"sizes": "257x257"
}]
}
This section is non-normative.
In the following example, the developer has included two shortcuts. Assuming the manifest's URL is https://example.com/manifest.webmanifest :
{
"shortcuts": [
{
"name": "Play Later",
"description": "View the list of podcasts you saved for later",
"url": "/play-later",
"icons": [
{
"src": "/icons/play-later.svg",
"type": "image/svg+xml"
}
]
},
{
"name": "Subscriptions",
"description": "View the list of podcasts you listen to",
"url": "/subscriptions?sort=desc"
}
]
}
This section is non-normative.
The
scope
member
tells
the
browser
which
documents
are
part
of
a
web
application,
and
which
are
not
-
and
hence,
to
which
set
of
web
pages
the
manifest
is
"
applied
"
when
the
user
navigates
around
a
web
site.
For
example,
{"scope":
"/"}
means
that
the
manifest
applies
to
every
document
in
an
origin.
On
the
other
hand,
{"scope":
"/racer/"}
means
that
only
documents
within
the
path
"/racer/"
are
within
scope
:
so
"/racer/race1.html",
"/racer/race2.html",
etc.
would
all
be
within
scope
,
but
"/elsewhere/"
and
anything
at
the
root
"/"
would
be
"out
of
scope"
and
the
manifest
wouldn't
apply
to
documents
in
those
paths.
Only
one
scope
path
is
supported.
See
§
6.
7.
Navigation
scope
for
the
technical
details.
Applying
a
manifest
means
that
any
members
that
affect
presentation
found
in
the
manifest
will
come
into
effect,
such
as
display
"fullscreen",
or
applying
a
particular
screen
orientation.
As
long
as
the
application
is
navigated
to
URLs
that
are
within
scope
,
the
browser
will
continue
to
apply
the
manifest.
However,
navigating
the
web
applications
"out
of
scope"
will
cause
the
manifest
to
no
longer
be
applied,
and
the
browser
will
apply
its
own
defaults.
This
will
cause,
for
example,
the
application
to
no
longer
be
displayed
in
fullscreen,
and
instead
be
displayed
as
a
regular
web
page
in
a
browser
tab.
It's
left
up
to
implementers
to
decide
how
to
deal
with
web
pages
being
navigated
in
and
out
of
scope.
See
§
1.16.4
1.17.4
Applying
the
manifest
for
the
technical
details.
Finally,
as
it's
possible
that
a
user
can
install
a
web
application
from
any
document
within
an
origin,
it's
good
practice
to
always
declare
a
scope
member
in
a
manifest.
If
the
scope
member
is
missing
from
the
manifest,
then
the
path
of
the
start_url
member
is
used
as
a
fallback.
And
if
the
start_url
member
is
also
missing,
then
the
document
URL
from
which
the
web
application
is
installed
gets
used
as
the
scope.
To
be
sure
you
don't
get
any
unexpected
navigation
behavior,
always
include
a
scope
member
preferably
set
to
"/"
.
dir
member
The
manifest's
dir
member
specifies
the
base
direction
for
the
localizable
members
of
the
manifest
.
The
dir
member's
value
can
be
set
to
one
of
the
text-direction
values
.
The localizable members are:
name
member.
short_name
member.
name
member.
short_name
member.
description
member.
The text-direction values are the following, implying that the value of the localizable members is by default:
When displaying the localizable members to an end-user, the use agent SHOULD :
To
process
the
dir
member
,
given
object
json
and
ordered
map
manifest
:
lang
member
The
manifest's
lang
member
is
a
string
in
the
form
of
a
language
tag
that
specifies
the
primary
language
for
the
values
of
the
manifest's
localizable
members
(as
knowing
the
language
can
also
help
with
directionality).
A
language
tag
is
a
string
that
matches
the
production
of
a
Language-Tag
defined
in
the
[
BCP47
]
specifications
(see
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
of
possible
values).
That
is,
a
language
range
is
composed
of
one
or
more
subtags
that
are
delimited
by
a
U+002D
HYPHEN-MINUS
("-").
For
example,
the
'
en-AU
'
language
range
represents
English
as
spoken
in
Australia,
and
'
fr-CA
'
represents
French
as
spoken
in
Canada.
Language
tags
that
meet
the
validity
criteria
of
[
RFC5646
]
section
2.2.9
that
can
be
verified
without
reference
to
the
IANA
Language
Subtag
Registry
are
considered
structurally
valid.
To
process
the
lang
member
,
given
object
json
and
ordered
map
manifest
:
false
,
return.
name
member
The
manifest's
name
member
is
a
string
that
represents
the
name
of
the
web
application
as
it
is
usually
displayed
to
the
user
(e.g.,
amongst
a
list
of
other
applications,
or
as
a
label
for
an
icon).
The
name
member
serves
as
the
accessible
name
of
an
installed
web
application
.
When
processing
a
manifest
,
the
process
a
text
member
algorithm
is
used
to
process
the
name
member.
short_name
member
The
manifest's
short_name
member
is
a
string
that
represents
a
short
version
of
the
name
of
the
web
application.
It
is
intended
to
be
used
where
there
is
insufficient
space
to
display
the
full
name
of
the
web
application.
When
processing
a
manifest
,
the
process
a
text
member
algorithm
is
used
to
process
the
short_name
member.
scope
member
The
manifest's
scope
member
is
a
string
that
represents
the
navigation
scope
of
this
web
application's
application
context
.
To
process
the
scope
member
,
given
object
json
and
ordered
map
manifest
:
icons
member
The
manifest's
icons
member
are
images
that
serve
as
iconic
representations
of
the
web
application
in
various
contexts.
For
example,
they
can
be
used
to
represent
the
web
application
amongst
a
list
of
other
applications,
or
to
integrate
the
web
application
with
an
OS
's
task
switcher
and/or
system
preferences.
If
there
are
multiple
equally
appropriate
images
in
icons
,
a
user
agent
MUST
use
the
last
one
declared
in
order
at
the
time
that
the
user
agent
collected
the
list
of
icons
.
If
the
user
agent
tries
to
use
an
icon
but
that
icon
is
determined,
upon
closer
examination,
to
be
inappropriate
(e.g.
because
its
content
type
is
unsupported),
then
the
user
agent
MUST
try
the
next-most-appropriate
icon
as
determined
by
examining
the
manifest
image
resource
's
members.
display
member
The
manifest's
display
member
represents
the
developer's
preferred
display
mode
for
the
web
application.
Its
value
is
one
of
the
display
modes
values
.
To
process
the
display
member
,
given
object
json
and
ordered
map
manifest
:
orientation
member
The
manifest's
orientation
member
is
a
string
that
serves
as
the
default
screen
orientation
for
all
top-level
browsing
contexts
of
the
web
application.
The
possible
values
are
those
of
the
OrientationLockType
enum,
which
in
this
specification
are
referred
to
as
the
orientation
values
(i.e.,
"any",
"natural",
"landscape",
"portrait",
"portrait-primary",
"portrait-secondary",
"landscape-primary",
or
"landscape-secondary").
If
the
user
agent
supports
the
value
of
the
orientation
member
as
the
default
screen
orientation
,
then
that
serves
as
the
default
screen
orientation
for
the
life
of
the
web
application
(unless
overridden
by
some
other
means
at
runtime).
This
means
that
the
user
agent
MUST
return
the
orientation
to
the
default
screen
orientation
any
time
the
orientation
is
unlocked
[
SCREEN-ORIENTATION
]
or
the
top-level
browsing
context
is
navigated
.
Although
the
specification
relies
on
the
[
SCREEN-ORIENTATION
]'s
OrientationLockType
,
it
is
OPTIONAL
for
a
user
agent
to
implement
the
[
SCREEN-ORIENTATION
]
API.
Supporting
the
[
SCREEN-ORIENTATION
]
API
is,
of
course,
encouraged.
Certain
UI/UX
concerns
and/or
platform
conventions
will
mean
that
some
screen
orientations
and
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).
To
process
the
orientation
member
,
given
JSON
json
and
ordered
map
manifest
:
start_url
member
The
manifest's
start_url
member
is
a
string
that
represents
the
start
URL
,
which
is
URL
that
the
developer
would
prefer
the
user
agent
load
when
the
user
launches
the
web
application
(e.g.,
when
the
user
clicks
on
the
icon
of
the
web
application
from
a
device's
application
menu
or
homescreen).
The
start_url
member
is
purely
advisory,
and
a
user
agent
MAY
ignore
it
or
provide
the
end-user
the
choice
not
to
make
use
of
it.
A
user
agent
MAY
also
allow
the
end-user
to
modify
the
URL
when,
for
instance,
a
bookmark
for
the
web
application
is
being
created
or
any
time
thereafter.
To
process
the
start_url
member
,
given
object
json
,
ordered
map
manifest
,
URL
manifest
URL
,
and
URL
document
URL
:
start_url
tracking
It's
conceivable
that
the
start_url
could
be
crafted
to
indicate
that
the
application
was
launched
from
outside
the
browser
(e.g.,
"start_url":
"index.html?launcher=homescreen"
).
This
can
be
useful
for
analytics
and
possibly
other
customizations.
However,
it
is
also
conceivable
that
developers
could
encode
strings
into
the
start_url
that
uniquely
identify
the
user
(e.g.,
a
server
assigned
UUID
).
This
is
fingerprinting/privacy
sensitive
information
that
the
user
might
not
be
aware
of.
Given the above, it is RECOMMENDED that, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify the start URL of an application.
theme_color
member
The
manifest's
theme_color
member
serves
as
the
default
theme
color
for
an
application
context.
What
constitutes
a
theme
color
is
defined
in
[
HTML
].
If
the
user
agent
honors
the
value
of
the
theme_color
member
as
the
default
theme
color
,
then
that
color
serves
as
the
theme
color
for
all
browsing
contexts
to
which
the
manifest
is
applied
.
However,
a
document
may
override
the
default
theme
color
through
the
inclusion
of
a
valid
[
HTML
]
meta
element
whose
name
attribute
value
is
"theme-color"
.
The user agent MAY ignore the theme color 's alpha component based on the context. For example, in most environments, the theme color cannot be transparent.
Implementors
MAY
override
the
value
defined
by
the
theme_color
member
to
support
prefers-color-scheme
.
When
processing
a
manifest
,
the
process
a
color
member
algorithm
is
used
to
process
the
theme_color
member.
background_color
member
The
manifest's
member
describes
the
expected
background
color
of
the
web
application.
It
repeats
what
is
already
available
in
the
application
stylesheet
but
can
be
used
by
the
user
agent
to
draw
the
background
color
of
a
web
application
for
which
the
manifest
is
known
before
the
files
are
actually
available,
whether
they
are
fetched
from
the
network
or
retrieved
from
disk.
background_color
The
background_color
member
is
only
meant
to
improve
the
user
experience
while
a
web
application
is
loading
and
MUST
NOT
be
used
by
the
user
agent
as
the
background
color
when
the
web
application's
stylesheet
is
available.
Implementors
MAY
override
the
value
defined
by
the
background_color
member
to
support
prefers-color-scheme
.
When
processing
a
manifest
,
the
process
a
color
member
algorithm
is
used
to
process
background_color
member.
shortcuts
member
The
manifest's
shortcuts
member
is
an
array
of
shortcut
item
s
that
provide
access
to
key
tasks
within
a
web
application.
How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.
To
process
the
shortcuts
member
,
given
object
json
,
manifest
,
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.
protocol_handlers
member
The
manifest's
protocol_handlers
member
is
an
array
of
protocol
handler
description
s
that
allows
a
web
application
to
handle
URL
protocols.
Protocol handlers could, for instance, be used for web app communication where one app directly invokes another and passes data via custom protocol links.
How protocol handlers are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.
To
process
the
protocol_handlers
member
,
given
object
json
,
manifest
,
and
manifest
URL
:
A user agent SHOULD ask users for permission before registering a protocol handler description protocol_handler s as the default handler for a protocol with the host operating system. A user agent MAY truncate the list of protocol handler description protocol_handlers presented in order to remain consistent with the conventions or limitations of the host operating system.
This section defines algorithms for processing a manifest , and applying a manifest .
A user agent MUST support the link type "manifest" and the associated steps for how to fetch and process the linked resource.
When instructed to ignore , the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.
The following algorithm provides an processing extension-point : other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm. They SHOULD NOT modify the existing values already in the manifest object.
The processing extension-point is meant to help avoid issues related to monkey patching .
The
steps
for
processing
a
manifest
are
given
by
the
following
algorithm.
The
algorithm
takes
link
el
and
a
Response
response
.
"{}"
).
dir
member
passing
json
and
manifest
.
lang
member
passing
json
and
manifest
.
start_url
member
passing
json
,
manifest
,
manifest
URL
,
and
document
URL
.
scope
member
passing
json
,
manifest
,
and
manifest
URL
.
display
member
passing
json
and
manifest
.
orientation
member
passing
json
,
manifest
.
protocol_handlers
member
passing
json
,
manifest
,
and
manifest
URL
.
related_applications
member
passing
json
and
manifest
.
shortcuts
member
passing
json
,
manifest
,
and
manifest
URL
.
Only
sRGB
colors,
and
colors
the
user
agent
can
convert
to
sRGB
without
any
outside
knowledge
(e.g.,
"AliceBlue"
),
are
supported.
For
example,
lab(…)
or
color(display-p3,
…)
can
be
converted
to
sRGB
without
outside
knowledge,
but
color(--custom-profile,
…)
would
require
finding
a
matching
"@color-profile"
rule
which
cannot
be
specified
in
the
manifest.
To process a color member , using JSON json , ordered map map , and string member :
To process a text member , given object json , ordered map map , and string member :
A processed manifest is applied to a top-level browsing context , meaning that the members of the processed manifest are affecting the presentation or behavior of a browsing context.
A top-level browsing context that has a manifest applied to it is referred to as an application context .
If
an
application
context
is
created
as
a
result
of
the
user
agent
being
asked
to
navigate
to
a
deep
link
,
the
user
agent
MUST
immediately
navigate
to
the
deep
link
with
historyHandling
set
to
"
replace
".
Otherwise,
when
the
application
context
is
created,
the
user
agent
MUST
immediately
navigate
to
the
start
URL
with
historyHandling
set
to
"
replace
".
The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.
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 its version of the manifest.
Each manifest image resource is an image resource that is conceptually part of a web application, suitable to use in various contexts depending on the semantics of the member that is using the object (e.g., an icon that is part of an application menu, etc.).
A
manifest
image
resource
differs
from
a
image
resource
in
that
it
can
have
an
additional
purpose
member.
User agents MAY modify the images associated with an manifest image resource to better match the platform’s visual style before displaying it to the user, for example by rounding the corners or painting it in a specific color. It is recommended that developers prepare their image resources for such scenarios to avoid losing important information through, e.g., change of color or clipped corners.
purpose
member
The
purpose
member
is
an
unordered
set
of
unique
space-separated
tokens
.
The
allowed
values
are
the
icon
purposes
.
When a manifest image resource is used as an icon , a developer can hint that the image is intended to serve some special purpose in the context of the host OS (i.e., for better integration). User agents SHOULD NOT use an icon other than for its stated icon purpose .
For
example,
an
icon
with
purpose
"
monochrome
"
could
be
used
as
a
badge
or
pinned
icon
with
a
solid
fill,
visually
distinct
from
an
application's
full
color
launch
icon.
The
user
agent
uses
the
value
of
the
purpose
member
as
a
hint
to
determine
where
and
how
an
purpose
is
displayed.
Unless
declared
otherwise
by
the
developer,
a
user
agent
can
use
an
icon
for
any
purpose
.
The icon purposes are as follows:
As the badge purpose "monochrome" is only supported by Firefox, it is at risk of being removed from the specification. Implementers should express interest in supporting this feature if they would like it to remain in the specification.
If
an
icon
contains
multiple
purposes,
it
could
be
used
for
any
of
those
purposes.
If
none
of
the
stated
purposes
are
recognized,
the
icon
is
totally
ignored.
For
example,
if
an
icon
has
purpose
"monochrome
fizzbuzz"
,
then
it
could
be
used
as
a
monochrome
icon,
as
"monochrome"
is
a
valid
purpose.
However,
if
an
icon
just
has
the
purpose
"fizzbuzz"
,
then
it
will
be
ignored.
To determine the purpose of an image , given object json :
The
security
policy
that
governs
whether
a
user
agent
can
fetch
an
icon
image
is
governed
by
the
img-src
directive
[
CSP3
]
associated
with
the
manifest's
owner
Document
.
Some platforms have their own preferred icon shape, but as web applications should work across multiple platforms, it is possible to indicate that an icon can have a user-agent-specified mask applied by adding the maskable purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different masks and background colors in different places throughout the platform.
The safe zone is the area within a maskable icon which is guaranteed to always be visible, regardless of user agent preferences. It is defined as a circle with center point in the center of the icon and with a radius of 2/5 (40%) of the icon size, which means the smaller of the icon width and height, in case the icon is not square.
Designers of maskable icons will want to make sure that all important parts are within the safe zone .
All pixels in this zone are guaranteed to be seen in all masks. Pixels outside the safe zone are not guaranteed to (but can) be visible depending on the applied mask.
The user agent MAY apply a mask of any size, making any pixels that are more than 2/5ths of the image size (minimum of width and height if non-square) away from the center (the safe zone ) transparent.
The user agent MUST NOT make any pixel within the safe zone transparent.
The user agent MAY enlarge the icon by adding additional padding.
If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid fill (e.g., white) of the user agent's choice.
It is suggested that designers avoid using transparent pixels in maskable icons.
By staying inside the safe zone , most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.
As the badge purpose "monochrome" is only supported by Firefox, it is at risk of being removed from the specification. Implementers should express interest in supporting this feature if they would like it to remain in the specification.
Some platforms enforce that icons be displayed with a solid fill such as a single color, where only the transparency of the icon can be declared in a manifest . As web applications need to work across multiple platforms, it is possible to indicate that an icon can have an user-agent-specified color applied by adding the monochrome purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different colors and padding in different places throughout the platform.
When presenting a monochrome icon, the user agent MUST NOT independently display the red component, green component, or blue component of a pixel. The user agent SHOULD display each pixel with its original alpha value, but with a red, green, and blue value of the user agent's choosing. It is RECOMMENDED that the user agent use the same color value for all pixels.
Designers of monochrome icons could set all pixels to black and only use transparency to create a silhouette of their icon.
The user agent MAY enlarge the icon by adding additional padding.
The user agent MAY add a background of any color behind transparent pixels, and SHOULD ensure that the background has sufficient contrast with the icon.
To process image resources , given array images , ordered map map , manifest URL and string member :
Each shortcut item is an object that represents a link to a key task or page within a web app. It has the following members:
A user agent can use these members to assemble a context menu to be displayed by the operating system when a user engages with the web app's icon. When the user invokes a shortcut from the operating system menu, the user agent SHOULD run launching a shortcut .
name
member
The
shortcut
item's
name
member
is
a
string
that
represents
the
name
of
the
shortcut
as
it
is
usually
displayed
to
the
user
in
a
context
menu.
short_name
member
The
shortcut
item's
short_name
member
is
a
string
that
represents
a
short
version
of
the
name
of
the
shortcut.
It
is
intended
to
be
used
where
there
is
insufficient
space
to
display
the
full
name
of
the
shortcut.
description
member
The
shortcut
item's
description
member
is
a
string
that
allows
the
developer
to
describe
the
purpose
of
the
shortcut.
User
agents
MAY
expose
this
information
to
assistive
technology.
url
member
The
shortcut
item's
url
member
is
a
URL
within
scope
of
a
processed
manifest
that
opens
when
the
associated
shortcut
is
activated.
icons
member
The
shortcut
item
's
icons
member
lists
images
that
serve
as
iconic
representations
of
the
shortcut
in
various
contexts.
When shortcut item shortcut having manifest is invoked, run the following steps:
To process a shortcut , given object item :
Each protocol handler description is an object that represents a protocol that the web application wants to handle. It has the following members:
A user agent SHOULD use these values to register the web application as a handler with the operating system. When the user activates a protocol handler URL, the user agent SHOULD run handling a protocol launch .
[
HTML
]'s
registerProtocolHandler
()
allows
web
sites
to
register
themselves
as
possible
handlers
for
particular
protocols.
What
constitutes
valid
protocol
and
url
values
for
protocol
handler
description
s
is
defined
in
that
API.
Also
note
that
the
[
HTML
]
API
uses
scheme
where
we
use
protocol
but
the
same
restrictions
apply.
protocol
member
The
protocol
member
of
a
protocol
handler
description
is
a
string
that
represents
the
protocol
to
be
handled,
such
as
mailto
or
web+auth
.
The
protocol
member
of
a
protocol
handler
description
is
equivalent
to
registerProtocolHandler
()
's
scheme
argument
defined
in
[
HTML
].
url
member
The url member of a protocol handler description is the URL within scope of the application that opens when the associated protocol is activated.
The
url
member
of
a
protocol
handler
description
is
equivalent
to
registerProtocolHandler
()
's
url
argument
defined
in
[
HTML
].
When a protocol handler description protocol_handler having manifest manifest is invoked, it goes through the same steps used to invoke a protocol handler defined in HTML , where the user agent SHOULD navigate to url and the appropriate browsing context is set to a new top level browsing context.
Privacy
concerns
for
custom
scheme
handling
are
detailed
in
the
Security
and
privacy
section
of
registerProtocolHandler
()
.
The user agent MUST ask for permission when using a protocol handler for the first time. This feature requires user interaction and a script cannot communicate with another application on its own.
The
related_applications
member
of
this
specification
currently
only
has
a
single
implementation.
As
such,
it
has
been
marked
"
at
risk
"
as
per
the
W3C
Process,
meaning
that:
[The feature] may be removed before advancement to Proposed Recommendation without a requirement to publish a new Candidate Recommendation.
The Web Apps Working Group is seeking a second implementation in order to keep this feature in the specification.
Each external application resource represents an application related to the web application.
An external application resource can have the following members, some of which are required to be a valid external application resource :
fingerprints
member
id
member
min_version
member
platform
member
url
member
A
valid
external
application
resource
MUST
have
platform
member,
and
either
an
url
or
an
id
member
(or
both).
platform
member
The
platform
member
represents
the
platform
this
external
application
resource
is
associated
with.
A
platform
represents
a
software
distribution
ecosystem
or
possibly
an
operating
system.
This
specification
does
not
define
the
particular
values
for
the
platform
member.
url
member
An
external
application
resource's
url
member
is
the
URL
where
the
application
can
be
found.
To
process
the
url
member
of
an
application
:
id
member
An
external
application
resource's
id
member
represents
the
id
which
is
used
to
represent
the
application
on
the
platform.
min_version
member
An
external
application
resource's
min_version
member
represents
the
minimum
version
of
the
application
that
is
considered
related
to
this
web
app.
This
version
is
a
string
with
platform-specific
syntax
and
semantics.
fingerprints
member
An
external
application
resource's
fingerprints
member
represents
an
array
of
fingerprints
.
A fingerprint represents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two members: type and value . Each of these are string s, but their syntax and semantics are platform-defined.
A common use case of a manifest is for a user agent to install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. A web application that is installed is known as a installed web application . That is, the manifest's members, or their defaults, are in effect on the top-level browsing context . This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.
For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When 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.
The
application's
name
is
derived
from
either
the
name
member
or
short_name
member.
When
either
the
name
member
or
the
short_name
member
is
missing,
empty,
or
the
wrong
type,
a
user
agent
MAY
use
the
name
member
as
a
fallback
for
the
short_name
member
or
short_name
member
as
the
fallback
for
the
name
member.
If
the
name
and
short_name
members
are
missing,
empty,
or
the
wrong
type,
a
user
agent
MAY
fallback
to
the
Document
to
find
suitable
replacements
for
missing
manifest
members
(e.g.,
using
application-name
in
place
of
name
or
short_name
).
Alternatively,
the
user
agent
SHOULD
assign
a
default
name
(e.g.,
"Untitled")
that
follows
platform
conventions.
Alternatively,
a
user
agent
MAY
allow
the
end-user
to
input
some
text
that
can
serve
as
the
application's
name
.
When
both
the
name
and
short_name
members
are
present,
it
is
left
up
to
implementations
to
decide
which
member
is
best
suited
for
the
space
available
(e.g.,
the
short_name
member
might
be
better
suited
for
the
space
available
underneath
an
icon).
It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL , origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.
It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.
User agents SHOULD provide a mechanism for the user to remove an installed web application application.
It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.
A display mode 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
.
Every display mode has a fallback chain , which is a list of display modes . The fallback chain for:
The steps for determining the web app's chosen display mode is given by the following algorithm. The algorithm takes a processed manifest manifest and returns a display mode .
The
above
loop
is
guaranteed
to
return
a
value
before
the
assertion,
due
to
the
fact
that
browser
is
in
every
mode's
fallback
chain
,
and
the
requirement
that
all
user
agents
support
the
browser
display
mode
.
The display modes values are:
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
.
'display-mode'
media
feature
Name: | display-mode |
---|---|
For: | @media |
Value: | fullscreen | standalone | minimal-ui | browser |
Type: | discrete |
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.
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 */
}
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 [ JSON ] and [ UNICODE-SECURITY ] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest , implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [ CSS-MIME ], [ ECMAScript-MIME ], [ HTML ].
As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.
As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [ URL ] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [ UNICODE-SECURITY ].
Developers
need
to
be
aware
of
the
security
considerations
discussed
throughout
the
[
CSP3
]
specification,
particularly
in
relation
to
making
data:
a
valid
source
for
the
purpose
of
inlining
a
manifest.
Doing
so
can
enable
XSS
attacks
by
allowing
a
manifest
to
be
included
directly
in
the
document
itself;
this
is
best
avoided
completely.
It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL , origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.
It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.
It's
conceivable
that
a
shortcut
url
could
be
crafted
to
indicate
that
the
application
was
launched
from
outside
the
browser
(e.g.,
"url":
"/task/?from=homescreen"
).
It
is
also
conceivable
that
developers
could
encode
strings
into
the
url
that
uniquely
identify
the
user
(e.g.,
a
server
assigned
UUID
).
This
is
fingerprinting/privacy
sensitive
information
that
the
user
might
not
be
aware
of.
When the web application is running, it is RECOMMENDED that the user agent provides the end-user a means to access common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.
Additionally, when applying a manifest that sets the display mode to anything except " browser ", it is RECOMMENDED that the user agent clearly indicate to the end-user that their are leaving the normal browsing context of a web browser. Ideally, launching or switching to a web application is performed in a manner that is consistent with launching or switching to other applications in the host platform. For example, a long and obvious animated transition, or speaking the text "Launching application X".
The
'display-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.
The
mime
type
application/manifest+json
is
the
application
manifest
media
type
.
Both
the
mime
type
and
the
.webmanifest
file
extension
are
registered
with
the
Internet
Assigned
Numbers
Authority
(
IANA
).
If the protocol over which the manifest is transferred supports the [ MIME-TYPES ] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the application manifest media type .
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , OPTIONAL , RECOMMENDED , SHOULD , and SHOULD NOT in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
There is only one class of product that can claim conformance to this specification: a user agent .
Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.
This section is non-normative.
This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the processing extension-point to hook into the steps for processing a manifest . Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.
To allow the community to easily find extensions, please add your extensions to the Extensions Registry .
When specifying a new member, don't override or monkey patch anything defined in this specification. Also, don't assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.
If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.
This section is non-normative.
Although proprietary extensions are undesirable, they can't realistically be avoided. 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"
...
}
This section is non-normative.
Extensions to this specification are being incubated in parallel by the Web Community, some of which are shipping in multiple browsers. If two or more browser engines end up supporting an incubated feature, then those features will become part of this specification in the future - allowing them to become a standard the Web Platform:
BeforeInstallPrompt
and
window.onappinstalled
event
BeforeInstallPrompt
event
and
window.onappinstalled
event
were
originally
part
of
this
specification.
However,
they
were
removed
from
the
specification
because
they
did
not
have
support
from
two
or
more
implementers.
You
can
now
find
them
in
the
BeforeInstallPrompt
event
and
window.onappinstalled
repository
at
the
WICG
.
share_target
member
share_target
member
registers
a
web
application
as
"target"
for
share
actions
(e.g.,
for
sharing
a
text,
a
URL,
or
a
file).
The
share_target
member
is
part
of
the
Web
Share
Target
specification,
being
incubated
at
the
WICG
.
This section is non-normative.
Several members of the Web App Manifest provide additional metadata related to how the web application may be presented in the context of a digital storefront, installation dialog, or other surfaces where the web application may be marketed or distributed. In an effort to support these use cases better, the following members have been moved into Web App Manifest - Application Information :
categories
description
iarc_rating_id
screenshots
link
and
meta
elements
This section is non-normative.
An
extensive
discussion
of
why
we
chose
to
use
JSON
instead
of
HTML
meta
/
link
tags
for
this
specification
is
available
on
GitHub
and
on
the
www-tag
list.
Below
is
a
short
summary
of
the
key
points
raised
in
those
discussions.
The
document
format
defined
in
this
specification
provides
a
unified
means
of
encapsulating
metadata
about
a
Web
application
in
a
way
that
we
hope
will
avoid
existing
pitfalls
with
both
proprietary
and
[
HTML
]'s
meta
/
link
tags.
Those
pitfalls
include:
Although it would be unrealistic to think that this specification won't bring its own set of problems, externalizing this data in the form of a manifest solves the problems described above. These problems are solved by:
meta
tags
are
currently
using,
especially
when
a
tag's
value
contains
several
sub-values.
In
addition,
standardizing
the
functionality
currently
provided
by
the
various
meta
tag-based
solutions
within
the
manifest
solves
the
problem
of
having
tproprietary
and
standard
[
HTML
]
tags
that
all
achieve
the
same
thing.
Of
course,
this
hinges
on
the
standard
actually
getting
implemented
by
browsers
and
those
browsers
getting
widely
deployed
to
users:
if
this
happens,
the
Web
community
might
be
able
to
retire
many
of
the
proprietary
meta
tags
plaguing
the
Web
at
the
time
of
writing.
More
information
about
the
proprietary
tags
can
be
found
in
the
Use
Cases
and
Requirements
for
Installable
Web
Apps
.
Lastly,
this
specification
does
not
make
the
standardized
solutions
found
in
[
HTML
]
redundant.
When
members
like
the
name
or
icons
is
missing
from
the
manifest,
user
agents
can
search
in
a
manifest's
owner
[
HTML
]
document
for
things
like
icons
and
the
application
name
(or
a
user
agent
might
even
fallback
to
proprietary
tags/metadata,
if
they
are
present
in
a
document).
This section is non-normative.
Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org . It is licensed under Apache 2.0 . It is kindly maintained by Mads Kristensen . If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.
This section is non-normative.
It is expected that authors will localize the content of a manifest by using one of the following options:
Accept-Language
"
header,
or
even
a
custom
HTTP
header).
Given the options above, developers need to be mindful of the end-user's privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user's preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [ TLS ] to reduce the chances of pervasive monitoring of their Web applications [ RFC7258 ].
This document attempts to address the Use Cases and Requirements for Installable Web Apps .
This section is non-normative.
The following are some significant changes that were made since First Public Working Draft:
This section is non-normative.
This document reuses text from the [ HTML ] specification, as permitted by the license of that specification.
Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.
Claudio Gomboli for icon example images.
Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.
application/manifest+json
§A.
background_color
§1.14
description
§3.3
dir
§1.2
display
§1.8
fingerprints
id
lang
§1.3
min_version
orientation
§1.9
prefer_related_applications
§1.13
protocol_handlers
§1.16
purpose
§2.1
related_applications
§1.12
scope
§1.6
shortcuts
§1.15
start_url
§1.10
theme_color
§1.11
CSS
)
Document
interface
Node
)
Document
)
response
)
HTML
element
link
element
meta
element
name
attribute
(for
meta
element)
list
)
set
)
string
)
iteration
)
list
)
list
)
@media
)
OrientationLockType
enum
url
)
url
)
url
)
url
)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: