Web Application Manifest

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2024/WD-appmanifest-20240702/
Latest published version:
https://www.w3.org/TR/appmanifest/
Latest editor's draft:
https://w3c.github.io/manifest/
History:
https://www.w3.org/standards/history/appmanifest/
Commit history
Editors:
Marcos Cáceres(Apple)
Kenneth Rohde Christiansen(Intel Corporation)
Matt Giuca(Google Inc.)
Diego González(Microsoft Corporation)
Daniel Murphy(Google Inc.)
Christian Liebel(Thinktecture AG)
Former editors:
Anssi Kostiainen(Intel Corporation) - Until
Aaron Gustafson(Microsoft Corporation) - Until
Mounir Lamouri(Google Inc.)
Rob Dolin(Microsoft Corporation)
Feedback:
GitHub w3c/manifest (pull requests, new issue, open issues)
Browser support:
caniuse.com

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademarkand permissive document licenserules apply.

Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. A list of currentW3C publications and the latest revision of this technical report can be found in theW3Ctechnical reports indexat https://www.w3.org/TR/.

Warning

This document was published by theWeb Applications Working Groupas a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement byW3Cand its Members.

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 W3CPatent Policy. W3Cmaintains 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 theW3CPatent Policy.

This document is governed by the 03 November 2023W3CProcess Document.

1. Web Application Manifest

Anapplication manifestis a [JSON] document that contains startup parameters and application defaults for when a web application is launched.

A manifest has an associatedmanifest URL, which is the [URL] from which themanifestwas fetched.

Amanifestcan have any of the following members at its root, all of which are optional. The members can appear in any order.

Note

1.1 Examples

This section is non-normative.

This section shows how developers can make use of the various features of this specification.

1.1.1 Typical structure

This section is non-normative.

The following shows a typicalmanifest.

Example1: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":"/",
"id":"superracer",
"start_url":"/start.html",
"display":"fullscreen",
"orientation":"landscape",
"theme_color":"aliceblue",
"background_color":"red"
}

1.1.3 Declaring multiple icons

This section is non-normative.

In the following example, the developer has made the following choices about the icons associated with the web application:

  • The developer has included two icons at the same size, but in two different formats. One is explicitly marked as WebP through the typemember. If the user agent doesn't support WebP, it falls back to the second icon of the same size. TheMIME typeof this icon can then be either determined via a HTTP header, or can besniffedby the user agent once the first few bytes of the icon are received.
  • The developer wants to use an SVG for greater than or equal to 257x257px. They've found that the SVG file looks too blurry at small sizes, even on high-density screens. To deal with this problem, the developer includes an SVG icon that is only used when the dimensions are at least 257px. Otherwise, the user agent uses the ICO file (hd_hi.ico), which includes a gamut of raster icons individually tailored for small display sizes.
Example3:Multiple icons 
{
"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"
}]
}

1.1.4 Creating shortcuts

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:

  • The first shortcut would be displayed with the text "Play Later". If the operating system supports icons for context menu items and it also supports SVG images for that purpose, the user agent would present https://example.com/icons/play-later.svgnext to the text. When launched, the user agent would instantiate a new top-level browsing contextand navigate to https://example.com/play-later.
  • The second shortcut would be displayed with the text "Subscriptions". When launched, the user agent would instantiate a newtop-level browsing contextand navigate to https://example.com/subscriptions?sort=desc.
Example4:Adding shortcuts 
{
"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"
}
]
}

1.1.5 Understanding "scope"

This section is non-normative.

Thescopemember 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 bewithin 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. See6. Navigation scopefor the technical details.

Applyinga 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. See1.17.5 Applying the manifestfor 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 ascopemember in a manifest. If the scopemember is missing from the manifest, then the path of thestart_urlmember is used as a fallback. And if thestart_urlmember 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 ascopemember preferably set to"/".

1.2 dirmember

Themanifest'sdirmember specifies the default string direction for thelocalizable membersof themanifest. Thedirmember's value can be set to a text-direction.

Thelocalizable membersare:

Thetext-directionsare the following, implying that the value of thelocalizable membersis by default:

"ltr"
Left-to-right text.
"rtl"
Right-to-left text.
"auto"(default)
Text direction is unknown. The user agent should use heuristics to estimate the display of the text, for example the first-strong algorithm as described in [UAX9].

Thetext-direction listis thelist« "ltr","rtl", "auto"».

Toprocess thedirmember,givenordered map jsonandordered mapmanifest:

  1. Setmanifest[ "dir" ] to "auto".
  2. Ifjson[ "dir" ] doesn'texistor ifjson[ "dir" ] is not astring,return.
  3. Iftext-direction listdoesn'tcontain json[ "dir" ], return.
  4. Setmanifest[ "dir" ] tojson[ "dir" ].

1.3 langmember

Themanifest'slangmember is astringin the form of a language tagthat specifies the language for the values of the manifest'slocalizable members.If thelangmember is not specified, the language is treated as unknown.

Note

Specifying the language improves the user experience by helping user agents select the most appropriate processing or resources, such as fonts, styling, hyphenation, or text-to-speech voices for accessibility.

Alanguage tagis astringthat matches the production of a well-formedLanguage-Tagdefined in [BCP47].

Note

Language tags are case-insensitive. Examples of language tags include 'fr' (French), 'en-AU' (English as spoken in Australia), or 'zh-Hans-CN' (Chinese as written in the Simplified Han script as spoken in China).

Toprocess thelangmember,givenordered map jsonandordered mapmanifest:

  1. Ifjson[ "lang" ] doesn'texistor ifjson[ "lang" ] is not astring,return.
  2. If callingIsStructurallyValidLanguageTag withjson[ "lang" ] returnsfalse,return.
  3. Setmanifest[ "lang" ] to the result of calling the CanonicalizeUnicodeLocaleId abstract operation withjson[ "lang" ].

1.4 namemember

Themanifest'snamemember is astringthat 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).

Thenamemember serves as theaccessible nameof an installed web application.

Note:Processing the `name` member

Whenprocessing a manifest,theprocess a text member algorithm is used to process thenamemember.

1.5 short_namemember

Themanifest'sshort_namemember is astringthat 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.

Note:Processing the `short_name` member

Whenprocessing a manifest,theprocess a text member algorithm is used to process theshort_namemember.

1.6 scopemember

Themanifest'sscopemember is astringthat represents thenavigation scopeof this web application'sapplication context.

Note:Default scope

Toprocess thescopemember,givenordered map jsonandordered mapmanifest:

  1. Setmanifest[ "scope" ] to the result ofparsing "."withmanifest[ "start_url" ] as the base URL.
  2. Ifjson[ "scope" ] is the empty string, then return.
  3. Letscopebe the result ofparsing json[ "scope" ] withmanifest URLas the base URL.
  4. Ifscopeis failure, return.
  5. Setscope'squeryandfragmentto null.
  6. Ifmanifest[ "start_url" ] is notwithin scopeof scope,return.
  7. Otherwise, setmanifest[ "scope" ] toscope.

1.7 iconsmember

Themanifest'siconsmember 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 anOS's task switcher and/or system preferences.

Note

1.8 displaymember

Themanifest'sdisplaymember represents the developer's preferreddisplay modefor the web application. Its value is a display mode.

Toprocess thedisplaymember,givenordered map jsonandordered mapmanifest:

  1. Setmanifest[ "display" ] to "browser".
  2. Ifjson[ "display" ] doesn'texistorjson[ "display" ] is not a astring,return.
  3. Ifdisplay modes listdoesn'tcontain json[ "display" ], return.
  4. Setmanifest[ "display" ] tojson[ "display" ].

1.9 orientationmember

Themanifest'sorientationmember is astringthat serves as thedefault screen orientationfor alltop-level browsing contextsof the web application. The possible values are those of theOrientationLockTypeenum, which in this specification are referred to as theorientation values (i.e., "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", or "landscape-secondary" ).

If the user agent supports the value of theorientation member as thedefault screen orientation,then that serves as thedefault screen orientationfor the life of the web application (unless overridden by some other means at runtime). This means that the user agentMUSTreturn the orientation to the default screen orientationany time the orientation is unlocked [SCREEN-ORIENTATION] or thetop-level browsing contextisnavigated.

Note

Although the specification relies on the [SCREEN-ORIENTATION]'s OrientationLockType,it isOPTIONALfor 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 andcannot 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 thedefault screen orientationof an application while inbrowserdisplay mode.

Note

Once the web application is running, other means can change the orientation of atop-level browsing context(such as via [SCREEN-ORIENTATION] API).

Toprocess theorientationmember,givenordered map jsonandordered mapmanifest:

  1. Ifjson[ "orientation" ] doesn'texistor json[ "orientation" ] is not astring,return.
  2. Ifjson[ "orientation" ] doesn'tcontainany of the orientation values,return.
  3. Setmanifest[ "orientation" ] tojson[ "orientation" ].

1.10 start_urlmember

Themanifest'sstart_urlmember is astringthat represents thestart URL,which is URLthat 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).

Thestart_urlmember is purely advisory, and a user agentMAYignoreit or provide the end-user the choice not to make use of it. A user agentMAYalso allow the end-user to modify the URL when, for instance, a bookmark for the web application is being created or any time thereafter.

Toprocess thestart_urlmember,givenordered map json,ordered mapmanifest,URL manifest URL,andURLdocument URL:

  1. Setmanifest[ "start_url" ] todocument URL.
  2. Ifjson[ "start_url" ] doesn'texistor json[ "start_url" ] is not astring,return.
  3. If the type ofjson[ "start_url" ] is notstring,or if json[ "start_url" ] is the empty string, return.
  4. Letstart URLbe the result ofparsing json[ "start_url" ], usingmanifest URLas the base URL.
  5. Ifstart URLis failure, return.
  6. Ifstart URLis notsame originasdocument URL, return.
  7. Otherwise, setmanifest[ "start_url" ] tostart URL.

1.10.1 Privacy consideration:start_urltracking

It's conceivable that thestart_urlcould 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 identifier, such as"?user=123","/user/123/", or"https://user123.foo.bar"). This is fingerprinting/privacy sensitive information that the user might not be aware of.

Note:Don't add identifiers to start URLs

It is bad practice for a developer to use thestart URLto include information that uniquely identifies a user, as it would represent a fingerprint that is not cleared when the user clears site data. However, nothing in this specification can practically prevent developers from doing this.

Given the above, it isRECOMMENDEDthat, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify thestart URLof an application.

A user agentMAYoffer other protections against this form of fingerprinting. For example, if a user clears data from an origin, the user agentMAYoffer to uninstall applications that are within scopeof that origin, thus removing the potential fingerprint from the application's start URL.

1.11 idmember

Themanifest'sidmember is astringthat represents theidentityfor the application. Theidentitytakes the form of a URL, which is same origin as thestart URL.

Theidentityis used by user agents to uniquely identify the application universally. When the user agent sees a manifest with an identitythat does not correspond to an already-installed application, itSHOULDtreat that manifest as a description of a distinct application, even if it is served from the same URL as that of another application. When the user agent sees a manifest where manifest[ "id" ] isequal(withexclude fragmentsOPTIONALLY set to true) to theidentityof an already-installed application, itSHOULDbe used as a signal that this manifest is a replacement for the already-installed application's manifest, and not a distinct application, even if it is served from a different URL than the one seen previously.

Note:Excluding fragments is best practice
Note

Theidentitycan be used by a service that collects lists of web applications to uniquely identify applications.

Note

Theidentityis processed like a URL but it doesn't point to a resource that can be navigated to, so it's not required to be within scope.

Toprocess theidmember,givenordered map json,ordered mapmanifest:

  1. Setmanifest[ "id" ] tomanifest[ "start_url" ].
  2. If the type ofjson[ "id" ] is notstring,return.
  3. Ifjson[ "id" ] is the empty string, return.
  4. Letbase originbemanifest[ "start_url" ]'sorigin.
  5. Letidbe the result ofparsingjson[ "id" ] withbase originas the base URL.
  6. Ifidis failure, return.
  7. Ifidis notsame originasmanifest[ "start_url" ], return.
  8. Setid'sfragmentto null.
  9. Setmanifest[ "id" ] toid.

1.12 theme_colormember

Themanifest'stheme_colormember serves as thedefault theme colorfor an application context. What constitutes a theme coloris defined in [HTML].

If the user agent honors the value of thetheme_color member as thedefault theme color,then that color serves as thetheme colorfor all browsing contexts to which the manifest isapplied.However, a document may override the default theme colorthrough the inclusion of a valid [HTML] metaelement whosenameattribute value is "theme-color".

The user agentMAYignore thetheme color'salpha componentbased on the context. For example, in most environments, thetheme colorcannot be transparent.

ImplementorsMAYoverride the value defined by the theme_colormember to supportprefers-color-scheme.

Note

Whenprocessing a manifest,theprocess a color member algorithm is used to process thetheme_colormember.

1.15 background_colormember

Themanifest'sbackground_colormember describes the expected background color of the web application. It repeats what is already available in the application stylesheet but can be used by theuser agentto 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.

Thebackground_colormember is only meant to improve the user experience while a web application is loading andMUST NOTbe used by theuser agentas the background color when the web application's stylesheet is available.

ImplementorsMAYoverride the value defined by the background_colormember to supportprefers-color-scheme.

Note

Whenprocessing a manifest,theprocess a color member algorithm is used to processbackground_colormember.

1.16 shortcutsmember

Themanifest'sshortcutsmember is anlistof shortcut items that provide access to key tasks within a web application.

Note

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.

Toprocess theshortcutsmember,givenordered map json,ordered mapmanifest,and URLmanifest URL:

  1. LetprocessedShortcutsbe a newlist.
  2. Setmanifest[ "shortcuts" ] toprocessedShortcuts.
  3. Ifjson[ "shortcuts" ] doesn'texistor json[ "shortcuts" ] is not alist,return.
  4. For eachentryofjson[ "shortcuts" ]:
    1. Letshortcutbeprocess a shortcutwith entryandmanifest[ "scope" ].
    2. Ifshortcutis failure, continue.
    3. AppendshortcuttoprocessedShortcuts.

A user agentSHOULDexpose 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 SHOULDrender the shortcuts in the same order as they are provided in the manifest. A user agentSHOULDrepresent the shortcuts in a manner consistent with exposure of an application icon's context menu in the host operating system. A user agentMAYtruncate the list of shortcuts presented in order to remain consistent with the conventions or limitations of the host operating system.

1.17 Manifest life-cycle

This section defines algorithms forprocessing a manifest,and applyingamanifest.

A user agentMUSTsupport the link type "manifest" and the associated steps for how to fetch and process the linked resource.

1.17.1 Processing the manifest

When instructed toignore,the user agentMUSTact as if whatever manifest, member, or value caused the condition is absent.

The following algorithm provides anprocessing 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. TheySHOULD NOT modify the existing values already in themanifest object.

The steps forprocessing a manifestare given by the following algorithm. The algorithm takes aURLdocument URL,a URLmanifest URL,and abyte sequencebodyBytes.

  1. Letjsonbe the result ofparse JSON bytes to an Infra valuepassingbodyBytes.
  2. If thejsonis a parsing exception, orjsonis not an ordered map:
    1. Setjsonto an emptyordered map.
  3. Letmanifestbe an emptyordered map.
  4. Process thedirmemberpassingjsonandmanifest.
  5. Process thelangmemberpassingjsonandmanifest.
  6. Process a text memberpassingjson,manifest,and "name".
  7. Process a text memberpassingjson,manifest,and "short_name".
  8. Process thestart_urlmemberpassingjson,manifest, manifest URL,anddocument URL.
  9. Process theidmemberpassingjsonandmanifest.
  10. If thedocument'sprocessed manifestis not null, anddocument'sprocessed manifest's id is notequaltomanifest[ "id" ], return.
  11. Process thescopememberpassingjson,manifest,and manifest URL.
  12. Process a color memberpassingjson,manifest,and "theme_color".
  13. Process a color memberpassingjson,manifest,and "background_color".
  14. Process thedisplaymemberpassingjsonandmanifest.
  15. Process image resourcespassingjson[ "icons" ], manifest,manifest URL,and "icons".
  16. Process theorientationmemberpassingjson, manifest.
  17. Process therelated_applicationsmemberpassingjson andmanifest.
  18. Process theshortcutsmemberpassingjson,manifest, andmanifest URL.
  19. Processing extension-point:process any proprietary and/or other supported members at this point in the algorithm.
  20. Letdocument's processed manifestbemanifest.

1.17.2 Processing color members

Note:Supported colors

OnlysRGBcolors, and colors the user agent can convert to sRGBwithout any outside knowledge (e.g.,"AliceBlue"), are supported. For example,lab(…)orcolor(display-p3,…)can be converted tosRGBwithout outside knowledge, but color(--custom-profile,…)would require finding a matching "@color-profile" rule which cannot be specified in the manifest.

Toprocess a color member,usingordered map json,ordered mapmap,and stringmember:

  1. Ifjson[member] doesn'texistorjson[member] is not astring,return.
  2. Letcolorbe the result ofparsingthe value of json[member] as a CSS color.
  3. Ifcoloris failure, return.
  4. Ifcolorcan be converted tosRGBusing solely information the user agent inherently knows, then convertcolor tosRGB.
  5. Ifcoloris notsRGBcolor, return.
  6. Setmap[member] tocolor.

1.17.3 Processing text members

Toprocess a text member,givenordered map json,ordered mapmap,and stringmember:

  1. Ifjson[member] doesn'texistsorjson[member] is not astring,return.
  2. Setmap[member] to the value ofjson[member].

1.17.4 Processing the manifest without a document

Theprocessing a manifeststeps are invoked by [HTML]'s processing steps for thelinkelement, butMAYalso be invoked by the user agent to process a manifest without an associated document.

In this case, to match the guarantees made by the corresponding steps in [HTML], the user agentSHOULDensure that at least at some point in the past:

Note:The rationale for these checks

1.17.5 Applying the manifest

Aprocessed manifestisappliedto atop-level browsing context,meaning that the members of the processed manifestare affecting the presentation or behavior of a browsing context.

Atop-level browsing contextthat has a manifest applied to it is referred to as anapplication context.

If anapplication contextis created as a result of the user agent being asked tonavigateto adeep link,the user agentMUSTimmediatelynavigateto thedeep link withhistoryHandlingset to "replace".Otherwise, when theapplication contextis created, the user agentMUST immediatelynavigateto thestart URLwith historyHandlingset to "replace".

Note

The appropriate time toapplya manifest is when the application contextis created and before navigationto thestart URLbegins.

1.17.6 Updating the manifest

As specified formanifestlink relation, the manifest is fetched and processed on every page load. When theprocessing a manifestis successful, user agentsMAYapply updated manifest to any current and futureapplication contextsassociated with the application.

For the purpose of updating, the following member are security-sensitive members,as they are presented during installation and on launch surfaces:

  1. short_name,
  2. icons
  3. name,

User agentsSHOULD NOTautomatically apply changes to security-sensitive memberswithoutexpress permissionfrom the user.

Instead, user agentsSHOULDpresent changes tosecurity-sensitive memberswith appropriate management options, so the user can make an informed decision about updating the web application.

The user agentMAYautomatically apply the changes if the update does not contain changes tosecurity-sensitive members.

Note:A user agent will not apply a partial update

2. Manifest image resources

Eachmanifest image resourceis animage resourcethat 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.).

Amanifest image resourcediffers from aimage resourcein that it can have an additionalpurposemember.

User agentsMAYmodify the images associated with anmanifest image resourceto 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.

2.1 purposemember

Thepurposemember is an unordered set of unique space-separated tokens.The allowed values are theicon purposes.

When amanifest image resourceis used as anicon,a developer can hint that the image is intended to serve some special purpose in the context of the hostOS(i.e., for better integration). User agentsSHOULD NOTuse an icon other than for its statedicon purpose.

Note

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 thepurposemember as a hint to determine where and how anpurposeis displayed. Unless declared otherwise by the developer, a user agent can use an icon forany purpose.

Theicon purposesare as follows:

monochrome
A user agent can present this icon where amonochrome icon with a solid fillis needed. The color information in the icon is discarded and only the alpha data is used. The icon can then be used by the user agent like a mask over any solid fill.
maskable
The image is designed withicon masks and safe zonein mind, such that any part of the image that is outside thesafe zonecan safely be ignored and masked away by the user agent.
any(default)
The user agent is free to display the icon where nopurposeis required. For example, amanifest image resourcewith a "any" purpose wouldn't be used in a context where "monochrome"is required.

Theicon purposes listis thelist« "monochrome","maskable","any"».

Note

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.

Todetermine the purpose of an image,givenordered mapjson:

  1. Ifjson[ "purpose" ] doesn'texistor if json[ "purpose" ] is not astring:
    1. Returnset« "any" ».
  2. Letkeywordsbe the result ofsplit on ASCII whitespacejson[ "purpose" ].
  3. Letpurposesbe newset.
  4. For eachkeywordofkeywords:
    1. Ificon purposes listdoesn'tcontainkeyword, thencontinue.
    2. Otherwise,appendkeywordtopurposes.
  5. Ifpurposesis empty,then return failure.
  6. Returnpurposes.

2.2 Content security policy

The security policy that governs whether auser agentcan fetch an icon image is governed by theimg-srcdirective [CSP3] associated with the manifest's ownerDocument.

2.3 Icon masks and safe zone

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 themaskablepurpose. 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.

Thesafe zoneis the area within amaskableicon 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.

Note

Designers ofmaskableicons will want to make sure that all important parts are within thesafe zone.

safe zone illustrated
Figure1 The safe zone is a centrally positioned circle, with radius 2/5 (40%) of the minimum of the icon's width and height.

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 agentMAYapply 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 (thesafe zone) transparent.

The user agentMUST NOTmake any pixel within the safe zone transparent.

The user agentMAYenlarge the icon by adding additional padding.

If the icon contains transparent pixels, the user agentMUST composite the icon onto a solid fill (e.g., white) of the user agent's choice.

Note

It is suggested that designers avoid using transparent pixels in maskable icons.

2.3.1 Examples of masks

Note

By staying inside thesafe 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.

2.3.1.1 Icons with "maskable" purpose
An icon over a checkerboard background
Figure2 ImageThe base image with transparent background
An icon in a purple circle (40% of the size) over a yellow background
Figure3 Safe zoneCircle with radius 2/5 (40%) of the icon size
2.3.1.2 Mask examples
An icon inside a rounded yellow square on a purple background
Figure4 Rounded square Android
An icon inside an extremely rounded yellow square on a purple background
Figure5 SquircleAndroid
An icon inside a rounded yellow circle on a purple background
Figure6 CircleAndroid
An icon inside a somewhat rounded yellow square on a purple background
Figure7 Rounded squareiOS
An icon on a yellow background
Figure8 FullbleedWindows

2.4 Monochrome icons and solid fills

Some platforms enforce that icons be displayed with asolid fillsuch as a single color, where only the transparency of the icon can be declared in amanifest.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 monochromepurpose. 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 amonochromeicon, the user agent MUST NOTindependently display the red component, green component, or blue component of a pixel. The user agentSHOULDdisplay each pixel with its original alpha value, but with a red, green, and blue value of the user agent's choosing. It isRECOMMENDEDthat the user agent use the same color value for all pixels.

Note

Designers ofmonochromeicons could set all pixels to black and only use transparency to create a silhouette of their icon.

The user agentMAYenlarge the icon by adding additional padding.

The user agentMAYadd a background of any color behind transparent pixels, andSHOULDensure that the background has sufficient contrast with the icon.

2.4.1 Example usage of monochrome icons

2.4.1.1 Usage examples
A black icon over a checkerboard background
Figure9 ImageThe base image with no color.
A dark gradient icon over a checkerboard background
Figure10 Gradient fillThe image filled in with a gradient.
A dark yellow icon over a light gray background
Figure11 Solid color fill with padding Filled in with the theme color from the manifest.

2.5 Processing image resources

Toprocess image resources,givenlistimages, ordered mapmap,manifest URLandstring member:

  1. LetimageResourcesbe a new list.
  2. Setmap[member] toimageResources.
  3. Ifimagesis notlist,return.
  4. For eachpotential imageof images:
    1. Letimagebe the result of runningprocess an image resource from JSONgivenpotential imageandmanifest URL.
    2. Ifimageis failure,continue.
    3. Letpurposesbedetermine the purpose of an image passingpotential image.
    4. Ifpurposesis failure,continue.
    5. Setimage[ "purpose" ] topurposes.
    6. AppendimagetoimageResources.

3. Shortcut items

Eachshortcut itemis an ordered mapthat 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 agentSHOULDrunlaunching a shortcut.

3.1 namemember

Theshortcut item'snamemember is astringthat represents the name of the shortcut as it is usually displayed to the user in a context menu.

3.2 short_namemember

Theshortcut item'sshort_namemember is astring 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.

3.3 descriptionmember

Theshortcut item'sdescriptionmember is astring that allows the developer to describe the purpose of the shortcut. User agentsMAYexpose this information to assistive technology.

3.4 urlmember

Theshortcut item'surlmember is a URLwithin scopeof aprocessed manifestthat opens when the associated shortcut is activated.

3.5 iconsmember

Theshortcut item'siconsmember lists images that serve as iconic representations of the shortcut in various contexts.

3.6 Launching a shortcut

Whenshortcut itemshortcuthaving manifestis invoked, run the steps tolaunch a web applicationwithmanifestandshortcut.url.

3.7 Processing shortcut items

Toprocess a shortcut,givenordered mapitemandscope,:

  1. Return failure if it's the case that:
    • itemis notordered map.
    • item[ "name" ] doesn'texist.
    • item[ "name" ] is the empty string.
    • item[ "url" ] doesn'texist.
    • item[ "url" ] is not astring.
  2. Leturlbe the result ofparsing item[ "url" ] withmanifest URLas the base URL.
  3. Ifurlis failure, return failure.
  4. Ifurlis notwithin scopeofscope,return failure.
  5. Letshortcutbeordered map«[ "url" →url, "name" →item[ "name" ] ]».
  6. Process image resourcespassingitem[ "icons" ],shortcut, manifest URL,and "icons".
  7. Returnshortcut.

4. External application resource

(Feature at Risk) Issue 956:related_applications is single engine feature

Therelated_applicationsmember 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.

Eachexternal application resourcerepresents an application related to the web application.

Anexternal application resourcecan have the following members, some of which are required to be avalid external application resource:

Avalid external application resourceMUSThaveplatformmember, and either anurlor anid member (or both).

4.1 platformmember

Theplatformmember represents theplatformthisexternal application resourceis associated with. Aplatformrepresents a software distribution ecosystem or possibly an operating system. This specification does not define the particular values for the platformmember.

4.2 urlmember

Anexternal application resource'surlmember is the URLwhere the application can be found.

Toprocess theurlmember of an application:

  1. Ifapplication URLis missing, return null.
  2. Otherwise,parseapplication URLand if the result is not failure, return the result. Otherwise return null.

4.3 idmember

Anexternal application resource'sidmember represents the id which is used to represent the application on the platform.

4.4 min_versionmember

Anexternal application resource'smin_versionmember represents the minimum version of the application that is considered related to this web app. This version is astringwith platform-specific syntax and semantics.

4.5 fingerprintsmember

Anexternal application resource'sfingerprintsmember represents anlistoffingerprints.

Afingerprintrepresents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two members:typeandvalue.Each of these arestrings, but their syntax and semantics are platform-defined.

5. Installable web applications

A common use case of a manifest is for a user agent to installa web application; whereby the user agent provides the end-user with a means of instantiating a newtop-level browsing contextthat has the manifest's membersappliedto it. A web application that is installed is known as ainstalled web application.That is, the manifest's members, or their defaults, are in effect on thetop-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 propertiesappliedto it.

Note

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. Whenlaunching a web application,the manifest is appliedby the user agent to thetop-level browsing contextprior to thestart URLbeing loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing thedisplay modeand screen orientation of the web application. Alternatively, and again as an example, the user agent couldinstallthe web application into a list of bookmarks within the user agent itself.

5.1 Application's name

Theapplication's nameis derived from either the namemember orshort_namemember.

When either thenamemember or the short_namemember is missing, empty, or the wrong type, a user agentMAYuse thenamemember as a fallback for theshort_namemember orshort_namemember as the fallback for thenamemember.

If thenameandshort_namemembers are missing, empty, or the wrong type, a user agentMAYfallback to the Documentto find suitable replacements for missing manifest members (e.g., usingapplication-namein place ofname orshort_name). Alternatively, the user agentSHOULD assign a default name (e.g., "Untitled" ) that follows platform conventions. Alternatively, a user agentMAYallow the end-user to input some text that can serve as theapplication's name.

When both thenameandshort_namemembers are present, it is left up to implementations to decide which member is best suited for the space available (e.g., the short_namemember might be better suited for the space available underneath an icon).

5.2 Launching a web application

At the discretion of the operating system or user agent, run the steps tolaunch a web applicationwith aprocessed manifest.

Note

This would typically take place when the user selects an installedweb app from an app launching UI surface e.g., a home screen, launcher or start menu.

The steps tolaunch a web applicationis given by the following algorithm. The algorithm takes aprocessed manifest manifest,an optionalURLtarget URL, an optionalPOST resourcePOST resourceand returns an application context.

target URL,if given,MUSTbewithin scopeof manifest.

Other specificationsMAYreplace this algorithm's steps with their own steps. This replacement will take effect for all invocations of launch a web application.

Note

This algorithm is replaceable to allow an experimentallaunch_handlermanifest field to configure the behavior of all web application launches. The replacement algorithm invokescreate a new application contextby default but under certain conditions behaves differently.

  1. Return the result of running the steps tocreate a new application contextpassingmanifest,target URLandPOST resource.

The steps tocreate a new application contextis given by the following algorithm. The algorithm takes aprocessed manifestmanifest,an optionalURLtarget URL,an optionalPOST resourcePOST resourceand returns anapplication context.

  1. Iftarget URLwas not given, settarget URLtostart URL.
  2. Lettraversablebe the result of running the steps tocreate a fresh top-level traversablewithtarget URLandPOST resource.
  3. Letbrowsing contextbe thetraversable'sactive browsing context.
  4. Applymanifesttobrowsing context.
  5. Returnbrowsing context.

5.3 Privacy and security considerations

It isRECOMMENDEDthat UI that affords the end user the ability to installa 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 isRECOMMENDEDthat 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 isinstalled- or by using an entirely different cache from that used for regular web browsing.

5.4 Uninstallation

User agentsSHOULDprovide a mechanism for the user to remove an installed web applicationapplication.

It isRECOMMENDEDthat 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.

7. Display modes

Adisplay moderepresents how the web application is being presented within the context of anOS(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.

This specification defines the followingdisplay modes:

fullscreen
Opens the web application with browser UI elements hidden and takes up the entirety of the available display area.
standalone
Opens the web application to look and feel like a standalone native application. This can include the application having a different window, its own icon in the application launcher, etc. In this mode, the user agent will exclude standard browser UI elements such as an URL bar, but can include other system UI elements such as a status bar and/or system back button.
minimal-ui
This mode is similar tostandalone,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.
browser (default)
Opens the web application using the platform-specific convention for opening hyperlinks in the user agent (e.g., in a browser tab or a new window).
Note

Thefullscreendisplay modeis orthogonal to, and works independently of, theFullscreen API Standard.Thefullscreendisplay modeaffects 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 modeset tofullscreen,while document.fullScreenElementreturnsnull,andfullscreenEnabled returnsfalse.

Once a user agentappliesa particulardisplay modeto an application context,it becomes thedefault display modefor thetop-level browsing context(i.e., it is used as the display mode when the window isnavigated). The user agentMAYoverride thedefault display modefor security reasons (e.g., thetop-level browsing contextisnavigatedto another origin) and/or the user agentMAYprovide the user with a means of switching to anotherdisplay mode.

When thedisplaymember is missing, or if there is no validdisplaymember, the user agent uses thebrowserdisplay modeas thedefault display mode. As such, the user agentMUSTsupport thebrowser display mode.

Everydisplay modehas afallback chain,which is a list ofdisplay modes.Thefallback chainfor:

  1. browseris «».
  2. minimal-uiis « "browser"».
  3. standaloneis « "minimal-ui", "browser"».
  4. fullscreenis « "standalone", "minimal-ui","browser"».

Thesteps for determining the web app's chosen display mode is given by the following algorithm. The algorithm takes a processed manifestmanifestand returns adisplay mode.

  1. processing extension-point:process any proprietary and/or other supported display modes at this point in the algorithm.
  2. If the user agent supportsmanifest[ "display" ], then return manifest[ "display" ].
  3. For eachfallback_modeof thefallback chainof manifest[ "display" ]:
    1. If the user agent supports thefallback_mode,then return fallback_mode.
Note

The above loop is guaranteed to return a value before the assertion, due to the fact thatbrowseris in every mode's fallback chain,and the requirement that all user agents support thebrowserdisplay mode.

Thedisplay modes listis thelist« "fullscreen","standalone","minimal-ui","browser"».

A user agentMUSTreflect the applieddisplay modeof the web application in thedisplay-modemedia feature [MEDIAQUERIES-5].

Note

A user agent will expose the actual display mode being applied — not necessarily the one declared in the manifest — via the display-modemedia feature, accessible through CSS or JavaScript. Note that this media feature will also reflect other display modes for a web page when a manifest is not being applied. For example, if the end-user puts the page into fullscreen, then the user agent would reflect this change to CSS and scripts via the display-modemedia feature.

8. Privacy and security considerations

This specification does not directly deal with high-value data. However,installed web applicationsand their data could be seen as "high value" (particularly from a privacy perspective).

As the manifest format is JSON and will 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 displayIRIsandIDNAaddresses 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 makingdata:a valid source for the purpose ofinlininga 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 isRECOMMENDEDthat UI that affords the end user the ability to installa 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 isRECOMMENDEDthat 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 shortcuturlcould 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 theurlthat uniquely identify the user (e.g., a server assignedUUID). This is fingerprinting/privacy sensitive information that the user might not be aware of.

When the web application is running, it isRECOMMENDEDthat 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 thedisplay modeto anything except "browser",it is RECOMMENDEDthat 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".

Thedisplaymember allows an origin some measure of control over a user agent’s native UI. After taking over the full screen, it could attempt to mimic the user interface of another application. This is also facilitated by the'display-mode'media feature [MEDIAQUERIES-5], through which a script can know the display mode of a web application.

A. IANAconsiderations

The mime typeapplication/manifest+jsonis theapplication manifest media type.Both the mime type and the .webmanifestfile extension are registeredwith the Internet Assigned Numbers Authority (IANA).

A.1 Media type registration

If the protocol over which the manifest is transferred supports the [MIME-TYPES] specification (e.g. HTTP), it isRECOMMENDEDthat the manifest be labeled with theapplication manifest media type.

Type name:
application
Subtype name:
manifest+json
Required parameters:
N/A
Optional parameters:
N/A
Encoding considerations:
Same as for application/json ([RFC7159] section 8.1)
Privacy and security considerations:
See8. Privacy and security considerations.
Applications that use this MIME type:
Web browsers
Additional information:
Magic number(s):
N/A
File extension(s):
.webmanifest
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
TheWeb Applications Working Groupcan be contacted at[email protected].
Intended usage:
COMMON
Restrictions on usage:
none
Author:
W3C's Web Applications Working Group.
Change controller:
W3C.

B.Conformance

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 wordsMAY,MUST,MUST NOT,OPTIONAL,RECOMMENDED,SHOULD,andSHOULD NOTin 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: auser agent.

Note

Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.

B.1 Extensibility

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 theprocessing extension-pointto hook into the steps forprocessing 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 theExtensions Registry.

When specifying a new member, don't override ormonkey 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 bugso the community is informed of what you are trying to do.

B.1.1 Proprietary manifest members

This section is non-normative.

Although proprietary extensions are undesirable, they can't realistically be avoided. If a user agent chooses to interpret a member in the manifest JSON that is not specified in this document, it can do so, but with care.

We encourage implementors adding proprietary extensions to consider whether they could become a standard (i.e. if it would make sense for a second user agent on a different platform to make use of that member, even if no other user agent has expressed interest right now). If so, we ask authors to design the API in a vendor-neutral way, and propose it as a standard (seeC. Incubations). If the new member is truly proprietary (i.e. will only ever make sense in the context of a proprietary ecosystem), use this process, and prefix it with the short name of that proprietary ecosystem to avoid name collisions.

Do not use vendor prefixes that you intend to later remove once it becomes a standard (those tend to stick around forever). Only use prefixes that will make sense now and into the future.

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 proprietary extensions.

Example10:Proprietary extensions 
{
...
"kpl_fancy_feature": "some/url/img",
"gmpc_awesome_thing": {... },
"blitzly_site_verification": "KEY_9864D0966935"
...
}
Note

In this example, we have deliberately chosen (made-up) names of things that could be external sites or services,notnames of browsers or browser vendors. These are not vendor prefixes belonging to the browser that invented them; they are prefixes of proprietary services.

C. Incubations

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:

BeforeInstallPromptandwindow.onappinstalledevent
TheBeforeInstallPromptevent andwindow.onappinstalledevent were originally part of this specification. However, they were removed from the specificationbecause they did not have support from two or more implementers. You can now find them in theBeforeInstallPrompt event andwindow.onappinstalledrepositoryat theWICG.
share_targetmember
Theshare_targetmember registers a web application as "target" for share actions (e.g., for sharing a text, a URL, or a file). The share_targetmember is part of theWeb Share Target specification, being incubated at theWICG.

D. Application Information

This section is non-normative.

Several members of the Web Application 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 intoWeb App Manifest - Application Information:

F. JSON Schema

This section is non-normative.

Developers interested in validatingmanifestdocuments can find an unofficialJSON schema for the manifest formatatschemastore.org.It is licensed underApache 2.0.It is kindly maintained byMads Kristensen.If you find any issues with the JSON schema, pleasefile a bugat theSchemaStore repositoryon GitHub.

Note:Web Manifest JSON Schema

G. Internationalization

This section is non-normative.

It is expected that authors will localize the content of a manifest by using one of the following options:

Dynamically setting the language:
This can include, for instance, asking the end-user what their preferred language is and dynamically adding or replacing the manifest link relationship to the document based on that language preference (e.g., using a URL like "manifest.php?lang=fr" ).
Using content-negotiation, or geotargeting, etc. on the server:
The server that hosts the web application could attempt to predetermine the end-user's language by usinggeotargetingor by using content negotiation (e.g., using an HTTP "Accept-Language" header [RFC9110], 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].

H. Use Cases and Requirements

This document attempts to address theUse Cases and Requirements for Installable Web Apps.

I.Issue summary

J. Change log

This section is non-normative.

The following are some significant changes that were made since First Public Working Draft:

K. Acknowledgements

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.

L.Index

L.1Terms defined by this specification

L.2Terms defined by reference

M.References

M.1Normative references

[accname-1.2]
Accessible Name and Description Computation 1.2.Bryan Garaventa; Melanie Sumner. W3C. 21 June 2024. W3C Working Draft. URL:https://www.w3.org/TR/accname-1.2/
[BCP47]
Tags for Identifying Languages.A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL:https://www.rfc-editor.org/rfc/rfc5646
[CSP3]
Content Security Policy Level 3.Mike West; Antonio Sartori. W3C. 18 June 2024. W3C Working Draft. URL:https://www.w3.org/TR/CSP3/
[css-color-4]
CSS Color Module Level 4.Chris Lilley; Tab Atkins Jr.; Lea Verou. W3C. 13 February 2024. W3C Candidate Recommendation. URL:https://www.w3.org/TR/css-color-4/
[CSS-MIME]
The text/css Media Type.H. Lie; B. Bos; C. Lilley. IETF. March 1998. Informational. URL:https://www.rfc-editor.org/rfc/rfc2318
[css-syntax-3]
CSS Syntax Module Level 3.Tab Atkins Jr.; Simon Sapin. W3C. 24 December 2021. W3C Candidate Recommendation. URL:https://www.w3.org/TR/css-syntax-3/
[dom]
DOM Standard.Anne van Kesteren. WHATWG. Living Standard. URL:https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript Internationalization API Specification.Ecma International. URL:https://tc39.es/ecma402/
[ECMAScript-MIME]
Scripting Media Types.B. Hoehrmann. IETF. April 2006. Informational. URL:https://www.rfc-editor.org/rfc/rfc4329
[fetch]
Fetch Standard.Anne van Kesteren. WHATWG. Living Standard. URL:https://fetch.spec.whatwg.org/
[HTML]
HTML Standard.Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL:https://html.spec.whatwg.org/multipage/
[image-resource]
Image Resource.Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 4 June 2021. W3C Working Draft. URL:https://www.w3.org/TR/image-resource/
[infra]
Infra Standard.Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL:https://infra.spec.whatwg.org/
[JSON]
The JavaScript Object Notation (JSON) Data Interchange Format.T. Bray, Ed.. IETF. December 2017. Internet Standard. URL:https://www.rfc-editor.org/rfc/rfc8259
[MEDIAQUERIES-5]
Media Queries Level 5.Dean Jackson; Florian Rivoal; Tab Atkins Jr.; Daniel Libby. W3C. 18 December 2021. W3C Working Draft. URL:https://www.w3.org/TR/mediaqueries-5/
[MIME-TYPES]
Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL:https://www.rfc-editor.org/rfc/rfc2046
[permissions]
Permissions.Marcos Caceres; Mike Taylor. W3C. 19 March 2024. W3C Working Draft. URL:https://www.w3.org/TR/permissions/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels.S. Bradner. IETF. March 1997. Best Current Practice. URL:https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
The JavaScript Object Notation (JSON) Data Interchange Format.T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL:https://www.rfc-editor.org/rfc/rfc7159
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words.B. Leiba. IETF. May 2017. Best Current Practice. URL:https://www.rfc-editor.org/rfc/rfc8174
[SCREEN-ORIENTATION]
Screen Orientation.Marcos Caceres. W3C. 9 August 2023. W3C Working Draft. URL:https://www.w3.org/TR/screen-orientation/
[UAX9]
Unicode Bidirectional Algorithm.Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. Unicode Consortium. 15 August 2023. Unicode Standard Annex #9. URL:https://www.unicode.org/reports/tr9/tr9-48.html
[UNICODE]
The Unicode Standard.Unicode Consortium. URL:https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Unicode Security Considerations.Mark Davis; Michel Suignard. Unicode Consortium. 19 September 2014. Unicode Technical Report #36. URL:https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL Standard.Anne van Kesteren. WHATWG. Living Standard. URL:https://url.spec.whatwg.org/

M.2Informative references

[FULLSCREEN]
Fullscreen API Standard.Philip Jägenstedt. WHATWG. Living Standard. URL:https://fullscreen.spec.whatwg.org/
[manifest-app-info]
Web App Manifest - Application Information.Aaron Gustafson. W3C. 21 August 2023. W3C Working Group Note. URL:https://www.w3.org/TR/manifest-app-info/
[mimesniff]
MIME Sniffing Standard.Gordon P. Hemsley. WHATWG. Living Standard. URL:https://mimesniff.spec.whatwg.org/
[RFC7258]
Pervasive Monitoring Is an Attack.S. Farrell; H. Tschofenig. IETF. May 2014. Best Current Practice. URL:https://www.rfc-editor.org/rfc/rfc7258
[RFC9110]
HTTP Semantics.R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2022. Internet Standard. URL:https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS-1]
Service Workers.Jake Archibald; Marijn Kruisselbrink. W3C. 12 July 2022. W3C Candidate Recommendation. URL:https://www.w3.org/TR/service-workers/
[TLS]
The Transport Layer Security (TLS) Protocol Version 1.2.T. Dierks; E. Rescorla. IETF. August 2008. Proposed Standard. URL:https://www.rfc-editor.org/rfc/rfc5246
[webidl]
Web IDL Standard.Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL:https://webidl.spec.whatwg.org/