index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>
      Web Application Manifest
    </title>
    <script src="https://www.w3.org/Tools/respec/respec-w3c" class=
    "remove"></script>
    <script class='remove'>
    var respecConfig = {
      mdn: true,
      previousPublishDate: "2013-12-17",
      specStatus: "ED",
      shortName: "appmanifest",
      prevVersion: "FPWD",
      previousMaturity: "WD",
      formerEditors: [
        {
          name: "Mounir Lamouri",
          company: "Google Inc.",
          companyURL: "https://www.google.com/",
        },
        {
          name: "Rob Dolin",
          company: "Microsoft Corporation",
          companyURL: "https://www.microsoft.com/",
        },
      ],
      editors: [
        {
          name: "Marcos Cáceres",
          company: "Apple",
          companyURL: "https://apple.com",
          w3cid: 39125,
        },
        {
          name: "Kenneth Rohde Christiansen",
          company: "Intel Corporation",
          companyURL: "https://intel.com/",
          w3cid: 57705,
        },
        {
          name: "Matt Giuca",
          company: "Google Inc.",
          companyURL: "https://www.google.com/",
          w3cid: 91260,
        },
        {
          name: "Aaron Gustafson",
          company: "Microsoft Corporation",
          companyURL: "https://microsoft.com/",
          w3cid: 43672,
        },
        {
          name: "Daniel Murphy",
          company: "Google Inc.",
          companyURL: "https://www.google.com/",
          w3cid: 90918,
        },
        {
          name: "Anssi Kostiainen",
          company: "Intel Corporation",
          companyURL: "https://intel.com/",
          w3cid: 41974,
        },
      ],
      group: "webapps",
      github: "https://github.com/w3c/manifest/",
      caniuse: {
        versions: 1,
        feature: "web-app-manifest",
        browsers: [
          "chrome",
          "and_chr",
          "edge",
          "and_ff",
          "ios_saf",
        ],
      },
      xref: "web-platform",
    };
    </script>
    <style>
      .icon-title {
        text-transform: uppercase;
        font-weight: bold;
      }

      .icons {
        display: flex;
        flex-direction: row;
        flex-wrap: wrap;
      }

      .icons > figure {
        text-align: left;
        margin: 0;
        padding: 10px;
        width: 188px;
      }

      .icons > figure > img {
        width: 188px;
        height: 188px;
        min-width: 188px;
        min-height: 188px;
      }

      .icons > figure .icon-title {
        display: block;
      }
    </style>
  </head>
  <body data-cite=
  "ENCODING SCREEN-ORIENTATION MEDIAQUERIES-5 IMAGE-RESOURCE MIMESNIFF">
    <section id='abstract'>
      <p>
        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.
      </p>
      <p>
        Using this metadata, user agents can provide developers with means to
        create user experiences that are more comparable to that of a native
        application.
      </p>
    </section>
    <section id="sotd">
      <aside class="warning">
        <p>
          Implementors need to be aware that this specification is not stable.
          However, aspects of this specification are shipping in at least one
          browser (see links to implementation status at the top of this
          document). <strong>Implementors who are not taking part in the
          discussions will find the specification changing out from under them
          in incompatible ways.</strong> Vendors interested in implementing
          this specification before it eventually reaches the Candidate
          Recommendation phase should <a href=
          "https://github.com/w3c/manifest/issues">subscribe to the repository
          on GitHub</a> and take part in the discussions.
        </p>
      </aside>
    </section>
    <section>
      <h2>
        Web Application Manifest
      </h2>
      <p>
        A <dfn data-export="" data-lt="manifest" data-local-lt=
        "manifest's">application manifest</dfn> is a [[JSON]] document that
        contains startup parameters and application defaults for when a web
        application is launched.
      </p>
      <p>
        A manifest has an associated <dfn>manifest URL</dfn>, which is the
        [[URL]] from which the <a>manifest</a> was fetched.
      </p>
      <p>
        A [=manifest=] can have any of the following members at its root, all
        of which are optional. The members can appear in any order.
      </p>
      <ul>
        <li>[=manifest/background_color=]
        </li>
        <li>[=manifest/dir=]
        </li>
        <li>[=manifest/display=]
        </li>
        <li>[=manifest/icons=]
        </li>
        <li>[=manifest/identity=]
        </li>
        <li>[=manifest/lang=]
        </li>
        <li>[=manifest/name=]
        </li>
        <li>[=manifest/orientation=]
        </li>
        <li>[=manifest/prefer_related_applications=]
        </li>
        <li>[=manifest/related_applications=]
        </li>
        <li>[=manifest/scope=]
        </li>
        <li>[=manifest/short_name=]
        </li>
        <li>[=manifest/shortcuts=]
        </li>
        <li>[=manifest/start_url=]
        </li>
        <li>[=manifest/theme_color=]
        </li>
      </ul>
      <aside class="note">
        <p>
          Although it is optional for any member to appear in a manifest, some
          user agents might require one or more to be present to take full
          advantage of the capabilities afforded by this specification.
        </p>
      </aside>
      <section class="informative">
        <h3>
          Examples
        </h3>
        <p>
          This section shows how developers can make use of the various
          features of this specification.
        </p>
        <section class="informative">
          <h3>
            Typical structure
          </h3>
          <p>
            The following shows a typical <a>manifest</a>.
          </p>
          <pre class="example json" title="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"
            }
          </pre>
        </section>
        <section class="informative">
          <h3>
            Using a `link` element to link to a manifest
          </h3>
          <p>
            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.
          </p>
          <pre class="example html" title="Linking to a manifest">
            &lt;!doctype&gt;
            &lt;html&gt;
            &lt;title&gt;Racer 3K&lt;/title&gt;

            &lt;!-- Startup configuration --&gt;
            &lt;link rel="manifest" href="manifest.webmanifest"&gt;

            &lt;!-- Fallback application metadata for legacy browsers --&gt;
            &lt;meta name="application-name" content="Racer3K"&gt;
            &lt;link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico"&gt;
            &lt;link rel="icon" sizes="512x512" href="hi_def.png"&gt;
          </pre>
          <aside class="note" title="File extension: .webmanifest or .json?">
            The IANA <a href=
            "https://www.iana.org/assignments/media-types/application/manifest+json">
            registered</a> file extension for the manifest is `.webmanifest`.
            Some web servers recognize this extension and transfer the file
            using the standardized <a>application manifest media type</a>
            ([=application\/manifest+json=]). Developers can also choose a
            different extension (e.g. `.json`) or none at all (e.g.
            `/api/GetManifest`), but are encouraged to transfer the manifest
            using the [=application\/manifest+json=] [=MIME type=], although
            any [=JSON MIME type=] is ok.
          </aside>
        </section>
        <section class="informative">
          <h3>
            Declaring multiple icons
          </h3>
          <p>
            In the following example, the developer has made the following
            choices about the icons associated with the web application:
          </p>
          <ul>
            <li>The developer has included two icons at the same size, but in
            two different formats. One is explicitly marked as WebP through the
            `type` member. If the user agent doesn't support WebP, it falls
            back to the second icon of the same size. The <a>MIME type</a> of
            this icon can then be either determined via a HTTP header, or can
            be <a data-lt="computed mime type">sniffed</a> by the user agent
            once the first few bytes of the icon are received.
            </li>
            <li>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.
            </li>
          </ul>
          <pre class="example json" title="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"
                }]
            }
          </pre>
        </section>
        <section class="informative">
          <h3>
            Creating shortcuts
          </h3>
          <p>
            In the following example, the developer has included two shortcuts.
            Assuming the manifest's URL is
            <samp>https://example.com/manifest.webmanifest</samp>:
          </p>
          <ul>
            <li>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
            <samp>https://example.com/icons/play-later.svg</samp> next to the
            text. When launched, the user agent would instantiate a new
            <a>top-level browsing context</a> and navigate to
            <samp>https://example.com/play-later</samp>.
            </li>
            <li>The second shortcut would be displayed with the text
            "Subscriptions". When launched, the user agent would instantiate a
            new <a>top-level browsing context</a> and navigate to
            <samp>https://example.com/subscriptions?sort=desc</samp>.
            </li>
          </ul>
          <pre class="example json" title="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"
                }
              ]
            }
          </pre>
        </section>
        <section class="informative">
          <h2>
            Understanding "scope"
          </h2>
          <p>
            The [=manifest/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.
          </p>
          <p>
            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
            [=URL/within scope=]: so "/racer/race1.html", "/racer/race2.html",
            etc. would all be [=URL/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 [[[#nav-scope]]] for the technical details.
          </p>
          <p>
            [=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
            [=URL/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 [[[#applying]]] for the technical details.
          </p>
          <p>
            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 [=manifest/scope=] member in a manifest. If the
            [=manifest/scope=] member is missing from the manifest, then the
            path of the [=manifest/start_url=] member is used as a fallback.
            And if the [=manifest/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 [=manifest/scope=] member preferably set
            to `"/"`.
          </p>
        </section>
      </section>
      <section>
        <h3>
          `dir` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">dir</dfn></code> member specifies the <dfn>base
          direction</dfn> for the <a>localizable members</a> of the
          <a>manifest</a>. The [=manifest/dir=] member's value can be set to a
          <a>text-direction</a>.
        </p>
        <p>
          The <dfn>localizable members</dfn> are:
        </p>
        <ul>
          <li>[=manifest/name=] member.
          </li>
          <li>[=manifest/short_name=] member.
          </li>
          <li>[=Shortcut item's=] [=shortcut item/name=] member.
          </li>
          <li>[=Shortcut item's=] [=shortcut item/short_name=] member.
          </li>
          <li>[=Shortcut item's=] [=shortcut item/description=] member.
          </li>
        </ul>
        <p>
          The <dfn>text-directions</dfn> are the following, implying that the
          value of the <a>localizable members</a> is by default:
        </p>
        <dl>
          <dt>
            "<dfn data-dfn-for="text-direction">ltr</dfn>"
          </dt>
          <dd>
            Left-to-right text.
          </dd>
          <dt>
            "<dfn data-dfn-for="text-direction">rtl</dfn>"
          </dt>
          <dd>
            Right-to-left text.
          </dd>
          <dt>
            "<dfn data-dfn-for="text-direction">auto</dfn>" (default)
          </dt>
          <dd>
            No explicit directionality.
          </dd>
        </dl>
        <p>
          The <dfn>text-direction list</dfn> is the [=list=] «
          "[=text-direction/ltr=]", "[=text-direction/rtl=]",
          "[=text-direction/auto=]" ».
        </p>
        <p>
          When displaying the <a>localizable members</a> to an end-user, the
          use agent SHOULD:
        </p>
        <ol class="algorithm">
          <li>If the <a>base direction</a> is [=text-direction/ltr=] or
          [=text-direction/rtl=], override <a data-cite="bidi#P3">Rule P3</a>
          of [[BIDI]], setting the paragraph embedding level to 0 if the
          <a>base direction</a> is [=text-direction/ltr=], or 1 if the <a>base
          direction</a> is [=text-direction/rtl=].
          </li>
          <li>Otherwise the <a>base direction</a> is "[=text-direction/auto=]",
          in which case determine the text's direction by applying
            <a data-cite="bidi#P1">Rule P1</a> of [[BIDI]].
          </li>
        </ol>
        <p>
          To <dfn>process the `dir` member</dfn>, given [=ordered map=]
          |json:ordered map| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>Set |manifest|["dir"] to "auto".
          </li>
          <li>If |json|["dir"] doesn't [=map/exist=] or if |json|["dir"] is not
          a [=string=], return.
          </li>
          <li>If [=text-direction list=] doesn't [=list/contain=]
          |json|["dir"], return.
          </li>
          <li>Set |manifest|["dir"] to |json|["dir"].
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `lang` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">lang</dfn></code> member is a <a>string</a> in the form of
          a <a>language tag</a> that specifies the primary language for the
          values of the manifest's <a>localizable members</a> (as knowing the
          language can also help with directionality).
        </p>
        <p>
          A <dfn>language tag</dfn> is a <a>string</a> that matches the
          production of a `Language-Tag` defined in the [[BCP47]]
          specifications (see the <a href=
          "https://www.iana.org/assignments/language-subtag-registry">IANA
          Language Subtag Registry</a> for an authoritative list of possible
          values). That is, a language range is composed of one or more
          <dfn>subtags</dfn> that are delimited by a U+002D HYPHEN-MINUS ("-").
          For example, the '`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.
        </p>
        <p>
          To <dfn>process the `lang` member</dfn>, given [=ordered map=]
          |json:ordered map| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If |json|["lang"] doesn't [=map/exist=] or if |json|["lang"] is
          not a [=string=], return.
          </li>
          <li>If calling <a data-cite=
          "ECMA-402#sec-isstructurallyvalidlanguagetag">IsStructurallyValidLanguageTag</a>
          with |json|["lang"] returns `false`, return.
          </li>
          <li>Set |manifest|["lang"] to the result of calling the
            <a data-cite="ECMA-402#sec-canonicalizeunicodelocaleid">CanonicalizeUnicodeLocaleId</a>
            abstract operation with |json|["lang"].
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `name` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">name</dfn></code> member is a <a>string</a> that
          represents the name of the web application as it is usually displayed
          to the user (e.g., amongst a list of other applications, or as a
          label for an icon).
        </p>
        <p>
          The [=manifest/name=] member serves as the <a data-cite=
          "accname-1.2#dfn-accessible-name">accessible name</a> of an
          [=installed web application=].
        </p>
        <p class="note" title="Processing the `name` member">
          When [=processing a manifest=], the [=process a text member=]
          algorithm is used to process the [=manifest/name=] member.
        </p>
      </section>
      <section>
        <h3>
          `short_name` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">short_name</dfn></code> member is a <a>string</a> that
          represents a short version of the name of the web application. It is
          intended to be used where there is insufficient space to display the
          full name of the web application.
        </p>
        <p class="note" title="Processing the `short_name` member">
          When [=processing a manifest=], the [=process a text member=]
          algorithm is used to process the [=manifest/short_name=] member.
        </p>
      </section>
      <section>
        <h3>
          `scope` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">scope</dfn></code> member is a <a>string</a> that
          represents the [=manifest/navigation scope=] of this web
          application's <a>application context</a>.
        </p>
        <aside class="note" title="Default scope">
          <p>
            The "default scope" (when [=manifest/scope=] member is missing,
            empty, or failure) is the start URL, but with its filename, query,
            and fragment removed.
          </p>
        </aside>
        <p>
          To <dfn>process the `scope` member</dfn>, given [=ordered map=]
          |json:ordered map| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>Set |manifest|["scope"] to the result of [=URL Parser|parsing=]
          "." with |manifest|["start_url"] as the base URL.
          </li>
          <li>If |json|["scope"] is the empty string, then return.
          </li>
          <li>Let |scope:URL| be the result of [=URL Parser|parsing=]
          |json|["scope"] with |manifest URL| as the base URL.
          </li>
          <li>If |scope| is failure, return.
          </li>
          <li>From |scope|, remove the [=url/query=] and [=url/fragment=]
          components.
          </li>
          <li>If |manifest|["start_url"] is not [=URL/within scope=] of
          |scope|, return.
          </li>
          <li>Otherwise, set |manifest|["scope"] to |scope|.
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `icons` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">icons</dfn></code> 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 <abbr title="Operating system">OS</abbr>'s task switcher and/or
          system preferences.
        </p>
        <p>
          If there are multiple equally appropriate images in
          [=manifest/icons=], a user agent MUST use the last one declared in
          order at the time that the user agent collected the list of
          [=manifest/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.
        </p>
        <aside class="note">
          <p>
            When [=processing a manifest=], the [=process image resources=]
            algorithm is used to process the [=manifest/icons=] member.
          </p>
        </aside>
      </section>
      <section>
        <h3>
          `display` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">display</dfn></code> member represents the developer's
          preferred <a>display mode</a> for the web application. Its value is a
          [=display mode=].
        </p>
        <p>
          To <dfn>process the `display` member</dfn>, given [=ordered map=]
          |json:ordered map| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>Set |manifest|["display"] to "browser".
          </li>
          <li>If |json|["display"] doesn't [=map/exist=] or |json|["display"]
          is not a a [=string=], return.
          </li>
          <li>If [=display modes list=] doesn't [=list/contain=]
          |json|["display"], return.
          </li>
          <li>Set |manifest|["display"] to |json|["display"].
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `orientation` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">orientation</dfn></code> member is a <a>string</a> that
          serves as the <a>default screen orientation</a> for all <a>top-level
          browsing contexts</a> of the web application. The possible values are
          those of the {{OrientationLockType}} enum, which in this
          specification are referred to as the <dfn>orientation values</dfn>
          (i.e., "any", "natural", "landscape", "portrait", "portrait-primary",
          "portrait-secondary", "landscape-primary", or "landscape-secondary").
        </p>
        <p>
          If the user agent supports the value of the [=manifest/orientation=]
          member as the <a>default screen orientation</a>, then that serves as
          the <a>default screen orientation</a> for the life of the web
          application (unless overridden by some other means at runtime). This
          means that the user agent MUST return the orientation to the
          <a>default screen orientation</a> any time the orientation is
          unlocked [[SCREEN-ORIENTATION]] or the <a>top-level browsing
          context</a> is <a>navigated</a>.
        </p>
        <p class="note">
          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.
        </p>
        <p>
          Certain UI/UX concerns and/or platform conventions will mean that
          some screen orientations and <dfn>cannot be used together</dfn>.
          Which orientations and display modes cannot be used together is left
          to the discretion of implementers. For example, for some user agents,
          it might not make sense to change the <a>default screen
          orientation</a> of an application while in `browser` <a>display
          mode</a>.
        </p>
        <p class="note">
          Once the web application is running, other means can change the
          orientation of a <a>top-level browsing context</a> (such as via
          [[SCREEN-ORIENTATION]] API).
        </p>
        <p>
          To <dfn>process the `orientation` member</dfn>, given [=ordered map=]
          |json:ordered map| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If |json|["orientation"] doesn't [=map/exist=] or
          |json|["orientation"] is not a [=string=], return.
          </li>
          <li>If |json|["orientation"] doesn't [=list/contain=] any of the
          [=orientation values=], return.
          </li>
          <li>Set |manifest|["orientation"] to |json|["orientation"].
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `start_url` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">start_url</dfn></code> member is a <a>string</a> that
          represents the <dfn>start URL</dfn> , which is <a>URL</a> that the
          developer would prefer the user agent load when the user launches the
          web application (e.g., when the user clicks on the icon of the web
          application from a device's application menu or homescreen).
        </p>
        <p>
          The [=manifest/start_url=] member is purely advisory, and a user
          agent MAY <a>ignore</a> it or provide the end-user the choice not to
          make use of it. A user agent MAY also allow the end-user to modify
          the URL when, for instance, a bookmark for the web application is
          being created or any time thereafter.
        </p>
        <p>
          To <dfn>process the `start_url` member</dfn>, given [=ordered map=]
          |json:ordered map|, [=ordered map=] |manifest:ordered map|, [=URL=]
          |manifest URL:URL|, and [=URL=] |document URL:URL|:
        </p>
        <ol class="algorithm">
          <li>Set |manifest|["start_url"] to |document URL|.
          </li>
          <li>If |json|["start_url"] doesn't [=map/exist=] or
          |json|["start_url"] is not a [=string=], return.
          </li>
          <li>If the type of |json|["start_url"] is not [=string=], or if
          |json|["start_url"] is the empty string, return.
          </li>
          <li>Let |start URL:URL| be the result of [=URL Parser|parsing=]
          |json|["start_url"], using |manifest URL| as the base URL.
          </li>
          <li>If |start URL| is failure, return.
          </li>
          <li>If |start URL| is not <a>same origin</a> as |document URL|,
          return.
          </li>
          <li>Otherwise, set |manifest|["start_url"] to |start URL|.
          </li>
        </ol>
        <aside class="example">
          <p>
            For example, if the value of [=manifest/start_url=] is
            <samp>../start_point.html</samp>, and the manifest's URL is
            <samp>https://example.com/resources/manifest.webmanifest</samp>,
            then the result of [=URL parser|parsing=] would be
            <samp>https://example.com/start_point.html</samp>.
          </p>
        </aside>
        <section>
          <h3>
            Privacy consideration: [=manifest/start_url=] tracking
          </h3>
          <p>
            It's conceivable that the [=manifest/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 <abbr>UUID</abbr>). This is fingerprinting/privacy
            sensitive information that the user might not be aware of.
          </p>
          <p>
            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 <a>start URL</a> of an application.
          </p>
          <p>
            Additionally, developers MUST NOT use the <a>start URL</a> to
            include information that uniquely identifies a user (e.g.,
            "?user=123" or "/user/123/", or "https://user123.foo.bar").
          </p>
        </section>
      </section>
      <section>
        <h3>
          `id` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">id</dfn></code> member is a <a>string</a> that represents
          the <dfn>identity</dfn> for the application. The [=identity=] takes
          the form of a URL, which is same origin as the start URL.
        </p>
        <p>
          The [=identity=] is used by user agents to uniquely identify the
          application universally. When the user agent sees a manifest with an
          [=identity=] that does not correspond to an already-installed
          application, it SHOULD treat 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"] is [=url/equal=] with [=URL serializer/exclude
          fragment|exclude fragment true=] to the [=identity=] of an
          already-installed application, it SHOULD be 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.
        </p>
        <p class="note">
          The [=identity=] can be used by a service that collects lists of web
          applications to uniquely identify applications.
        </p>
        <p class="note">
          The [=identity=] is processed like a URL but it doesn't point to a
          resource that can be navigated to, so it's not required to be
          [=URL/within scope=].
        </p>
        <p>
          To <dfn>process the `id` member</dfn>, given [=ordered map=]
          |json:JSON|, [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>Set |manifest|["id"] to |manifest|["start_url"].
          </li>
          <li>If the type of |json|["id"] is not [=string=], return.
          </li>
          <li>If |json|["id"] is the empty string, return.
          </li>
          <li>Let |base origin| be |manifest|["start_url"]'s [=url/origin=].
          </li>
          <li>Let |id:URL| be the result of [=URL Parser|parsing=] |json|["id"]
          with |base origin| as the base URL.
          </li>
          <li>If |id| is failure, return.
          </li>
          <li>If |id| is not [=same origin=] as |manifest|["start_url"],
          return.
          </li>
          <li>Set |manifest|["id"] to |id|.
          </li>
        </ol>
        <aside class="example" title="Resulting ids">
          <p>
            Below table shows some example `id`s resulting from the [=process
            the `id` member=] steps.
          </p>
          <table class="data">
            <tr>
              <th>
                |json|["id"]
              </th>
              <th>
                |manifest|["start_url"]
              </th>
              <th>
                |manifest|["id"]
              </th>
            </tr>
            <tr>
              <td>
                <i>undefined</i>
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
            </tr>
            <tr>
              <td>
                <i>undefined</i>
              </td>
              <td>
                "https://example.com/my-app/#here"
              </td>
              <td>
                "https://example.com/my-app/#here"
              </td>
            </tr>
            <tr>
              <td>
                ""
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
            </tr>
            <tr>
              <td>
                "/"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/"
              </td>
            </tr>
            <tr>
              <td>
                "foo"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/foo"
              </td>
            </tr>
            <tr>
              <td>
                "./foo"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/foo"
              </td>
            </tr>
            <tr>
              <td>
                "https://example.com/foo"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/foo"
              </td>
            </tr>
            <tr>
              <td>
                "https://anothersite.com/foo"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
            </tr>
            <tr>
              <td>
                "😀"
              </td>
              <td>
                "https://example.com/my-app/start"
              </td>
              <td>
                "https://example.com/%F0%9F%98%80"
              </td>
            </tr>
          </table>
          <p>
            Since [=manifest/id=] is resolved against [=manifest/start_url=]'s
            [=URL/origin=], providing "../foo", "foo", "/foo", "./foo" all
            resolves to the same [=identifier=]. It is As such, best practice
            is to use a leading "/" to be explicit that the id is a
            root-relative url path. Also, standard encoding/decoding rules are
            apply to the id processing algorithm, as per the [[[URL]]].
          </p>
        </aside>
      </section>
      <section>
        <h3>
          `theme_color` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">theme_color</dfn></code> member serves as the <dfn>default
          theme color</dfn> for an application context. What constitutes a
          <dfn>theme color</dfn> is defined in [[HTML]].
        </p>
        <p>
          If the user agent honors the value of the [=manifest/theme_color=]
          member as the <a>default theme color</a>, then that color serves as
          the <a>theme color</a> for all browsing contexts to which the
          manifest is <a>applied</a>. However, a document may override the
          <a>default theme color</a> through the inclusion of a valid [[HTML]]
          [^meta^] element whose [^meta/name^] attribute value is
          `"theme-color"`.
        </p>
        <p data-cite="CSS-COLOR-4">
          The user agent MAY ignore the <a>theme color</a>'s [=alpha
          component=] based on the context. For example, in most environments,
          the <a>theme color</a> cannot be transparent.
        </p>
        <p>
          Implementors MAY override the value defined by the
          [=manifest/theme_color=] member to support <a data-xref-type=
          "css-descriptor" data-xref-for="@media">prefers-color-scheme</a>.
        </p>
        <p class="note">
          When [=processing a manifest=], the [=process a color member=]
          algorithm is used to process the [=manifest/theme_color=] member.
        </p>
      </section>
      <section>
        <h3>
          `related_applications` member
        </h3>
        <aside class="issue" data-number="956"></aside>
        <p>
          A <dfn>related application</dfn> is an application accessible to the
          underlying application platform that has a relationship with the web
          application.
        </p>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">related_applications</dfn></code> member lists <a>related
          applications</a> and serves as an indication of such a relationship
          between web application and <a>related applications</a>. This
          relationship is unidirectional and unless a listed application claims
          the same relationship, the <a>user agent</a> MUST NOT assume a
          bi-directional endorsement.
        </p>
        <p>
          Example of usages of the `related_applications` could be a crawler
          that would use that information to gather more information about the
          web application or a browser that could suggest a listed application
          as an alternative if the user wants to install the web application.
        </p>
        <p>
          To <dfn>process the `related_applications` member</dfn>, given
          [=ordered map=] |json:ordered map| and [=ordered map=]
          |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>Let |relatedApplications:list| be a new [=list=].
          </li>
          <li>Set |manifest|["related_applications"] to |relatedApplications|.
          </li>
          <li>If |json|["related_applications"] doesn't [=map/exist=] or
          |json|["related_applications"] is not a [=list=], return.
          </li>
          <li>[=list/For each=] <var>app</var> of
          |json|["related_applications"]:
            <ol>
              <li>If neither <var>app</var>["id"] nor <var>app</var>["url"] are
              missing:
                <ol>
                  <li>Set <var>app</var>["url"] to the result of running
                  <a>process the `url` member of an application</a> given <var>
                    app</var>["url"].
                  </li>
                  <li>[=list/append=] <var>app</var> to
                  <var>relatedApplications</var>.
                  </li>
                </ol>
              </li>
            </ol>
          </li>
          <li>Set <var>relatedApplications</var>.
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `prefer_related_applications` member
        </h3>
        <aside class="issue" data-number="957"></aside>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">`prefer_related_applications`</dfn></code> member is a
          [=boolean=] that is used as a hint for the user agent to say that
          <a>related applications</a> should be preferred over the web
          application. If the `prefer_related_applications` member is set to
          `true`, and the user agent wants to suggest to install the web
          application, the user agent might want to suggest installing one of
          the <a>related applications</a> instead.
        </p>
      </section>
      <section>
        <h3>
          `background_color` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">`background_color`</dfn></code> 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 <a>user agent</a> 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.
        </p>
        <p>
          The [=manifest/background_color=] member is only meant to improve the
          user experience while a web application is loading and MUST NOT be
          used by the <a>user agent</a> as the background color when the web
          application's stylesheet is available.
        </p>
        <p>
          Implementors MAY override the value defined by the
          [=manifest/background_color=] member to support <a data-xref-type=
          "css-descriptor" data-xref-for="@media">prefers-color-scheme</a>.
        </p>
        <p class="note">
          When [=processing a manifest=], the [=process a color member=]
          algorithm is used to process [=manifest/background_color=] member.
        </p>
      </section>
      <section>
        <h3>
          `shortcuts` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
          "manifest">shortcuts</dfn></code> member is an [=list=] of
          <a>shortcut item</a>s that provide access to key tasks within a web
          application.
        </p>
        <aside class="note">
          <p>
            Shortcuts could, for instance, be used to link directly to a user's
            timeline within a social media application or to their recent
            orders in an e-commerce context.
          </p>
          <p>
            Developers are encouraged to order their shortcuts by priority,
            with the most critical shortcuts appearing first in the list.
          </p>
        </aside>
        <p>
          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.
        </p>
        <p>
          To <dfn>process the `shortcuts` member</dfn>, given [=ordered map=]
          |json:ordered map|, [=ordered map=] |manifest:ordered map|, and
          [=URL=] |manifest URL:URL|:
        </p>
        <ol class="algorithm">
          <li>Let |processedShortcuts:list| be a new [=list=].
          </li>
          <li>Set |manifest|["shortcuts"] to |processedShortcuts|.
          </li>
          <li>If |json|["shortcuts"] doesn't [=map/exist=] or
          |json|["shortcuts"] is not a [=list=], return.
          </li>
          <li>[=list/For each=] |entry:ordered map| of |json|["shortcuts"]:
            <ol>
              <li>Let |shortcut:ordered map| be [=process a shortcut=] with
              |entry| and |manifest|["scope"].
              </li>
              <li>If |shortcut| is failure, continue.
              </li>
              <li>[=list/Append=] |shortcut| to |processedShortcuts|.
              </li>
            </ol>
          </li>
        </ol>
        <p>
          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.
        </p>
      </section>
      <section>
        <h2>
          Manifest life-cycle
        </h2>
        <p>
          This section defines algorithms for [=processing a manifest=], and
          <a>applying</a> a <a>manifest</a>.
        </p>
        <p>
          A user agent MUST support the link type "manifest" and the associated
          steps for how to fetch and process the linked resource.
        </p>
        <section id="processing">
          <h3>
            Processing the manifest
          </h3>
          <p>
            When instructed to <dfn>ignore</dfn>, the user agent MUST act as if
            whatever manifest, member, or value caused the condition is absent.
          </p>
          <p>
            The following algorithm provides an <dfn data-dfn-for=
            "application manifest" data-export="">processing
            extension-point</dfn>: other specifications that add new members to
            the manifest are encouraged to hook themselves into this
            specification at this point in the algorithm. They SHOULD NOT
            modify the existing values already in the <var>manifest</var>
            object.
          </p>
          <p class="note">
            The [=application manifest/processing extension-point=] is meant to
            help avoid <a href=
            "https://annevankesteren.nl/2014/02/monkey-patch">issues related to
            monkey patching</a>.
          </p>
          <p>
            The steps for <dfn data-export="" data-local-lt=
            "processing">processing a manifest</dfn> are given by the following
            algorithm. The algorithm takes a [=URL=] |document URL:URL|, a
            [=URL=] |manifest URL:URL|, and a [=byte sequence=] |bodyBytes|.
          </p>
          <ol class="algorithm">
            <li>Let |json| be the result of [=parse JSON bytes to an Infra
            value=] passing |bodyBytes|.
            </li>
            <li>If the |json| is a parsing exception, or |json| is not an
            [=ordered map=]:
              <ol>
                <li>Set |json:ordered map| to an empty [=ordered map=].
                </li>
              </ol>
            </li>
            <li>Let |manifest:ordered map| be an empty [=ordered map=].
            </li>
            <li>[=Process the `dir` member=] passing |json| and |manifest|.
            </li>
            <li>[=Process the `lang` member=] passing |json| and |manifest|.
            </li>
            <li>[=Process a text member=] passing |json|, |manifest|, and
            "name".
            </li>
            <li>[=Process a text member=] passing |json|, |manifest|, and
            "short_name".
            </li>
            <li>[=Process the `start_url` member=] passing |json|, |manifest|,
            |manifest URL|, and |document URL|.
            </li>
            <li>[=Process the `id` member=] passing |json| and |manifest|.
            </li>
            <li>If the [=document=]'s [=document|processed manifest=] is not
            null, and [=document=]'s [=document|processed manifest=]'s id is
            not [=URL/equal=] with [=URL serializer/exclude fragment|exclude
            fragment true=] to |manifest|["id"], return.
            </li>
            <li>[=Process the `scope` member=] passing |json|, |manifest|, and
            |manifest URL|.
            </li>
            <li>[=Process a color member=] passing |json|, |manifest|, and
            "theme_color".
            </li>
            <li>[=Process a color member=] passing |json|, |manifest|, and
            "background_color".
            </li>
            <li>[=Process the `display` member=] passing |json| and |manifest|.
            </li>
            <li>[=Process image resources=] passing |json|["icons"],
            |manifest|, |manifest URL|, and "icons".
            </li>
            <li>[=Process the `orientation` member=] passing |json|,
            |manifest|.
            </li>
            <li>[=Process the `related_applications` member=] passing |json|
            and |manifest|.
            </li>
            <li>[=Process the `shortcuts` member=] passing |json|, |manifest|,
            and |manifest URL|.
            </li>
            <li>[=application manifest/Processing extension-point=]: process
            any proprietary and/or other supported members at this point in the
            algorithm.
            </li>
            <li>Let [=document=]'s <dfn data-export="" data-dfn-for="Document">
              processed manifest</dfn> be |manifest|.
            </li>
          </ol>
        </section>
        <section data-cite="CSS-COLOR-4 CSS-SYNTAX-3">
          <h2>
            Processing color members
          </h2>
          <p class="note" title="Supported colors">
            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.
          </p>
          <p>
            To <dfn>process a color member</dfn>, using [=ordered map=]
            |json:ordered map|, [=ordered map=] |map:ordered map|, and
            [=string=] |member:string|:
          </p>
          <ol class="algorithm">
            <li>If |json|[member] doesn't [=map/exist=] or |json|[member] is
            not a [=string=], return.
            </li>
            <li>Let |color| be the result of [=CSS/parsing=] the value of
            |json|[member] as a CSS color.
            </li>
            <li>If |color| is failure, return.
            </li>
            <li>If |color| can be converted to [=sRGB=] using solely
            information the user agent inherently knows, then convert |color|
            to [=sRGB=].
            </li>
            <li>If |color| is not [=sRGB=] color, return.
            </li>
            <li>Set |map|[member] to |color|.
            </li>
          </ol>
        </section>
        <section>
          <h2>
            Processing text members
          </h2>
          <p>
            To <dfn>process a text member</dfn>, given [=ordered map=]
            |json:ordered map|, [=ordered map=] |map:ordered map|, and
            [=string=] |member:string|:
          </p>
          <ol class="algorithm">
            <li>If |json|[|member|] doesn't [=map/exists=] or |json|[|member|]
            is not a [=string=], return.
            </li>
            <li>Set |map|[member] to the value of |json|[|member|].
            </li>
          </ol>
        </section>
        <section>
          <h3>
            Processing the manifest without a document
          </h3>
          <p>
            The [=processing a manifest=] steps are invoked by [[HTML]]'s
            processing steps for the [^link^] element, but MAY also be invoked
            by the user agent to process a manifest without an associated
            [=document=].
          </p>
          <p>
            In this case, to match the guarantees made by the corresponding
            steps in [[HTML]], the user agent SHOULD ensure that at least at
            some point in the past:
          </p>
          <ul>
            <li>there was at least one [=document=] that is [=same origin=] as
            |document URL:URL| that has a [^link^] element
            |linkElement:HTMLLinkElement| with a [^link/rel^] of
            [^link/rel/manifest^] and a [^link/href^] that resolves to
            |manifest URL:URL|, and that
            </li>
            <li>if |manifest URL| is not [=same origin=] as |document URL|, the
            |bodyBytes:byte sequence| data was [=fetch|fetched=] with a [=CORS
            Request=] whose <a data-xref-type="http-header">`Origin`</a> is
            |document URL|'s [=url/origin=], and whose [=Request/credentials
            mode=] is set to the [=CORS settings attribute credentials mode=]
            for |linkElement|'s [^link/crossorigin^] attribute.
            </li>
          </ul>
          <aside class="note" title="The rationale for these checks">
            <p>
              This provision allows user agents to perform app installations
              using a manifest without having to first load a document that
              links to the manifest (e.g. when installing an app onto the
              user's device via a sync service). But the above recommendations
              ask the user agent to verify that, when an application scope is
              on origin A and the manifest is on a different origin B, there is
              a bidirectional relationship between the two origins.
            </p>
            <p>
              The first check ensures that at least some page on origin A links
              to the manifest on origin B (otherwise, it would be possible for
              a manifest on origin B to control the metadata for an
              unaffiliated app on origin A).
            </p>
            <p>
              The second check ensures that origin B allows (via the [=CORS
              protocol=]) its manifest to be applied by origin A, and also that
              the manifest is fetched with or without credentials, as agreed by
              both origins, as it would if going directly through the document.
            </p>
          </aside>
        </section>
        <section>
          <h3 id="applying">
            Applying the manifest
          </h3>
          <p>
            A [=Document/processed manifest=] is <dfn data-export=""
            data-local-lt="apply|applying">applied</dfn> to a <a>top-level
            browsing context</a>, meaning that the members of the
            [=Document/processed manifest=] are affecting the presentation or
            behavior of a browsing context.
          </p>
          <p>
            A <a>top-level browsing context</a> that has a manifest applied to
            it is referred to as an <dfn data-export="">application
            context</dfn>.
          </p>
          <p>
            If an <a>application context</a> is created as a result of the user
            agent being asked to <a>navigate</a> to a <a>deep link</a>, the
            user agent MUST immediately <a>navigate</a> to the <a>deep link</a>
            with <var>historyHandling</var> set to "`replace`". Otherwise, when
            the <a>application context</a> is created, the user agent MUST
            immediately <a>navigate</a> to the <a>start URL</a> with
            <var>historyHandling</var> set to "`replace`".
          </p>
          <aside class="note">
            <p>
              The <a>start URL</a> is not necessarily the value of the
              [=manifest/start_url=] member: the user or user agent could have
              changed it when the application was <a>installed</a>.
            </p>
          </aside>
          <p>
            The appropriate time to <a>apply</a> a manifest is when the
            <a>application context</a> is created and before
            [=navigate|navigation=] to the <a>start URL</a> begins.
          </p>
        </section>
        <section id="updating">
          <h3>
            Updating the manifest
          </h3>
          <p>
            As specified for [^link/rel/manifest^] link relation, the manifest
            is fetched and processed on every page load. When the [=processing
            a manifest=] is successful, user agents MAY apply updated manifest
            to any current and future <a>application contexts</a> associated
            with the application.
          </p>
          <p>
            For the purpose of updating, the following member are
            <dfn>security-sensitive members</dfn>, as they are presented during
            installation and on launch surfaces:
          </p>
          <ol>
            <li>[=manifest/short_name=],
            </li>
            <li>[=manifest/icons=]
            </li>
            <li>[=manifest/name=],
            </li>
          </ol>
          <p data-cite="permissions">
            User agents SHOULD NOT automatically apply changes to
            [=security-sensitive members=] without [=express permission=] from
            the user.
          </p>
          <p>
            Instead, user agents SHOULD present changes to [=security-sensitive
            members=] with appropriate management options, so the user can make
            an informed decision about updating the web application.
          </p>
          <p>
            The user agent MAY automatically apply the changes if the update
            does not contain changes to [=security-sensitive members=].
          </p>
          <aside class="note" title=
          "A user agent will not apply a partial update">
            <p>
              When the update contains changes both to [=security-sensitive
              members=] and other members, a user agent won't automatically
              partially update. For example, the user agent could present
              options to the user:
            </p>
            <ol>
              <li>Accept the update
              </li>
              <li>Uninstall the web app
              </li>
            </ol>
          </aside>
        </section>
      </section>
    </section>
    <section>
      <h2>
        Manifest image resources
      </h2>
      <p>
        Each <dfn>manifest image resource</dfn> 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.).
      </p>
      <p>
        A [=manifest image resource=] differs from a [=image resource=] in that
        it can have an additional [=manifest image resource/purpose=] member.
      </p>
      <p>
        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.
      </p>
      <section>
        <h3>
          `purpose` member
        </h3>
        <p>
          The <code><dfn data-dfn-for=
          "manifest image resource">purpose</dfn></code> member is an
          <a>unordered set of unique space-separated tokens</a>. The allowed
          values are the <a>icon purposes</a>.
        </p>
        <p>
          When a [=manifest image resource=] is used as an <dfn>icon</dfn>, 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 <a>icon
          purpose</a>.
        </p>
        <p class="note">
          For example, an icon with purpose "[=icon 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 [=manifest image resource/purpose=] member as a
          hint to determine where and how an [=manifest image
          resource/purpose=] is displayed. Unless declared otherwise by the
          developer, a user agent can use an icon for [=icon purpose/any|any
          purpose=].
        </p>
        <p>
          The <dfn>icon purposes</dfn> are as follows:
        </p>
        <dl>
          <dt>
            <dfn data-dfn-for="icon purpose">monochrome</dfn>
          </dt>
          <dd>
            A user agent can present this icon where a <a href=
            "#monochrome-icons-and-solid-fills">monochrome icon with a solid
            fill</a> is 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.
          </dd>
          <dt>
            <dfn data-dfn-for="icon purpose">maskable</dfn>
          </dt>
          <dd>
            The image is designed with <a href="#icon-masks">icon masks and
            safe zone</a> in mind, such that any part of the image that is
            outside the <a>safe zone</a> can safely be ignored and masked away
            by the user agent.
          </dd>
          <dt>
            <dfn data-dfn-for="icon purpose">any</dfn> (default)
          </dt>
          <dd>
            The user agent is free to display the icon in any context.
          </dd>
        </dl>
        <p>
          The <dfn>icon purposes list</dfn> is the [=list=] « "[=icon
          purpose/monochrome=]", "[=icon purpose/maskable=]", "[=icon
          purpose/any=]" ».
        </p>
        <p class="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.
        </p>
        <p>
          To <dfn>determine the purpose of an image</dfn>, given [=ordered
          map=] |json:image|:
        </p>
        <ol class="algorithm">
          <li>If |json|["purpose"] doesn't [=map/exist=] or if
          |json|["purpose"] is not a [=string=]:
            <ol>
              <li>Return [=set=] « "any" ».
              </li>
            </ol>
          </li>
          <li>Let |keywords:list&lt;string&gt;| be the result of [=split on
          ASCII whitespace=] |json|["purpose"].
          </li>
          <li>Let |purposes:set| be new [=set=].
          </li>
          <li>[=set/For each=] |keyword:string| of |keywords|:
            <ol>
              <li>If [=icon purposes list=] doesn't [=list/contain=] |keyword|,
              then [=iteration/continue=].
              </li>
              <li>Otherwise, [=set/append=] |keyword| to |purposes|.
              </li>
            </ol>
          </li>
          <li>If |purposes| [=list/is empty=], then return failure.
          </li>
          <li>Return |purposes|.
          </li>
        </ol>
      </section>
      <section>
        <h3>
          Content security policy
        </h3>
        <p>
          The security policy that governs whether a <a>user agent</a> can
          fetch an icon image is governed by the `img-src` directive [[CSP3]]
          associated with the manifest's owner {{Document}}.
        </p>
        <aside class="example" title="Content security policy of icons">
          <p>
            For example, given the following `img-src` directive in the
            `Content-Security-Policy` HTTP header of the manifest's owner
            {{Document}}:
          </p>
          <pre class="http">
            HTTP/1.1 200 OK
            Content-Type: text/html
            Content-Security-Policy: img-src icons.example.com

            &lt;!doctype&gt;
            &lt;html&gt;
            &lt;link rel="manifest" href="manifest.webmanifest"&gt;
          </pre>
          <p>
            And given the following `manifest.webmanifest`:
          </p>
          <pre class="json">
            {
              "name": "custom manifest",
              "start_url": "https://boo",
              "icons": [
                {
                  "src": "//icons.example.com/lowres"
                },
                {
                  "src": "//other.com/hi-res"
                }
              ]
            }
          </pre>
          <p>
            The fetching of icon resources from `icons.example.com/lowres`
            would succeed, while fetching from `other.com/hi-res` would fail.
          </p>
        </aside>
      </section>
      <section id="icon-masks">
        <h2>
          Icon masks and safe zone
        </h2>
        <p>
          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 [=icon purpose/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.
        </p>
        <p>
          The <dfn>safe zone</dfn> is the area within a [=icon
          purpose/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.
        </p>
        <p class="note">
          Designers of [=icon purpose/maskable=] icons will want to make sure
          that all important parts are within the <a>safe zone</a>.
        </p>
        <figure>
          <img src="images/safe-zone.svg" width="340" height="340" alt=
          "safe zone illustrated">
          <figcaption>
            The safe zone is a centrally positioned circle, with radius 2/5
            (40%) of the minimum of the icon's width and height.
          </figcaption>
        </figure>
        <p>
          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.
        </p>
        <p>
          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 <a>safe zone</a>)
          transparent.
        </p>
        <p>
          The user agent MUST NOT make any pixel within the safe zone
          transparent.
        </p>
        <p>
          The user agent MAY enlarge the icon by adding additional padding.
        </p>
        <p>
          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.
        </p>
        <p class="note">
          It is suggested that designers avoid using transparent pixels in
          maskable icons.
        </p>
        <section>
          <h3>
            Examples of masks
          </h3>
          <p class="note">
            By staying inside the <a>safe zone</a>, 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.
          </p>
          <h2 class="icon-title">
            Icons with "maskable" purpose
          </h2>
          <div class="icons">
            <figure>
              <img src="images/icon-plain.svg" alt=
              "An icon over a checkerboard background">
              <figcaption>
                <span class="icon-title">Image</span> <span>The base image with
                transparent background</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/icon-safe-zone.svg" alt=
              "An icon in a purple circle (40% of the size) over a yellow background">
              <figcaption>
                <span class="icon-title">Safe zone</span> <span>Circle with
                radius 2/5 (40%) of the icon size</span>
              </figcaption>
            </figure>
          </div>
          <h2 class="icon-title">
            Mask examples
          </h2>
          <div class="icons">
            <figure>
              <img src="images/icon-mask-android-roundsquare.svg" alt=
              "An icon inside a rounded yellow square on a purple background">
              <figcaption>
                <span class="icon-title">Rounded square</span>
                <span>Android</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/icon-mask-android-squircle.svg" alt=
              "An icon inside an extremely rounded yellow square on a purple background">
              <figcaption>
                <span class="icon-title">Squircle</span> <span>Android</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/icon-mask-android-circle.svg" alt=
              "An icon inside a rounded yellow circle on a purple background">
              <figcaption>
                <span class="icon-title">Circle</span> <span>Android</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/icon-mask-ios.svg" alt=
              "An icon inside a somewhat rounded yellow square on a purple background">
              <figcaption>
                <span class="icon-title">Rounded square</span> <span>iOS</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/icon-mask-windows.svg" alt=
              "An icon on a yellow background">
              <figcaption>
                <span class="icon-title">Fullbleed</span> <span>Windows</span>
              </figcaption>
            </figure>
          </div>
        </section>
      </section>
      <section>
        <h2>
          Monochrome icons and solid fills
        </h2>
        <aside class="issue atrisk" data-number="905"></aside>
        <p>
          Some platforms enforce that icons be displayed with a <dfn>solid
          fill</dfn> 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
          [=icon purpose/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.
        </p>
        <p>
          When presenting a [=icon purpose/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.
        </p>
        <p class="note">
          Designers of [=icon purpose/monochrome=] icons could set all pixels
          to black and only use transparency to create a silhouette of their
          icon.
        </p>
        <p>
          The user agent MAY enlarge the icon by adding additional padding.
        </p>
        <p>
          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.
        </p>
        <section>
          <h3>
            Example usage of monochrome icons
          </h3>
          <h2 class="icon-title">
            Usage examples
          </h2>
          <div class="icons">
            <figure>
              <img src="images/monochrome-icon-plain.svg" alt=
              "A black icon over a checkerboard background">
              <figcaption>
                <span class="icon-title">Image</span> <span>The base image with
                no color.</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/monochrome-icon-gradient.svg" alt=
              "A dark gradient icon over a checkerboard background">
              <figcaption>
                <span class="icon-title">Gradient fill</span> <span>The image
                filled in with a gradient.</span>
              </figcaption>
            </figure>
            <figure>
              <img src="images/monochrome-icon-tinted.svg" alt=
              "A dark yellow icon over a light gray background">
              <figcaption>
                <span class="icon-title">Solid color fill with padding</span>
                <span>Filled in with the theme color from the manifest.</span>
              </figcaption>
            </figure>
          </div>
        </section>
      </section>
      <section>
        <h3>
          Processing image resources
        </h3>
        <p>
          To <dfn>process image resources</dfn>, given [=list=] |images:list|,
          [=ordered map=] |map:ordered map|, |manifest URL:URL| and [=string=]
          |member:string|:
        </p>
        <ol class="algorithm">
          <li>Let |imageResources:List&lt;Image&nbsp;Resources&gt;| be a new
          [=list=].
          </li>
          <li>Set |map|[member] to |imageResources|.
          </li>
          <li>If |images| is not [=list=], return.
          </li>
          <li>[=list/For each=] |potential image:Manifest image resource| of
          |images|:
            <ol>
              <li>Let |image:ordered map| be the result of running [=process an
              image resource from JSON=] given |potential image| and |manifest
              URL|.
              </li>
              <li>If |image| is failure, [=iteration/continue=].
              </li>
              <li>Let |purposes:set| be [=determine the purpose of an image=]
              passing |potential image|.
              </li>
              <li>If |purposes| is failure, [=iteration/continue=].
              </li>
              <li>Set |image|["purpose"] to |purposes|.
              </li>
              <li>[=list/Append=] |image| to |imageResources|.
              </li>
            </ol>
          </li>
        </ol>
      </section>
    </section>
    <section>
      <h2>
        Shortcut items
      </h2>
      <p>
        Each <dfn data-local-lt="Shortcut item's">shortcut item</dfn> is an
        [=ordered map=] that represents a link to a key task or page within a
        web app. It has the following members:
      </p>
      <ul>
        <li>[=shortcut item/name=]
        </li>
        <li>[=shortcut item/short_name=]
        </li>
        <li>[=shortcut item/description=]
        </li>
        <li>[=shortcut item/url=]
        </li>
        <li>[=shortcut item/icons=]
        </li>
      </ul>
      <p>
        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 <a>launching a shortcut</a>.
      </p>
      <section>
        <h3>
          `name` member
        </h3>
        <p>
          The [=shortcut item's=] <code><dfn data-dfn-for=
          "shortcut item">name</dfn></code> member is a <a>string</a> that
          represents the name of the shortcut as it is usually displayed to the
          user in a context menu.
        </p>
      </section>
      <section>
        <h3>
          `short_name` member
        </h3>
        <p>
          The [=shortcut item's=] <code><dfn data-dfn-for=
          "shortcut item">short_name</dfn></code> member is a <a>string</a>
          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.
        </p>
      </section>
      <section>
        <h3>
          `description` member
        </h3>
        <p>
          The [=shortcut item's=] <code><dfn data-dfn-for=
          "shortcut item">description</dfn></code> member is a <a>string</a>
          that allows the developer to describe the purpose of the shortcut.
          User agents MAY expose this information to assistive technology.
        </p>
      </section>
      <section>
        <h3>
          `url` member
        </h3>
        <p>
          The [=shortcut item's=] <code><dfn data-dfn-for=
          "shortcut item">url</dfn></code> member is a URL [=manifest/within
          scope=] of a [=Document/processed manifest=] that opens when the
          associated shortcut is activated.
        </p>
      </section>
      <section>
        <h3>
          `icons` member
        </h3>
        <p>
          The <a>shortcut item</a>'s <code><dfn data-dfn-for=
          "shortcut item">icons</dfn></code> member lists images that serve as
          iconic representations of the shortcut in various contexts.
        </p>
      </section>
      <section>
        <h3>
          <dfn>Launching a shortcut</dfn>
        </h3>
        <p>
          When <a>shortcut item</a> <var>shortcut</var> having
          <var>manifest</var> is invoked, run the steps to [=launch a web
          application=] with <var>manifest</var> and <var>shortcut.url</var>.
        </p>
      </section>
      <section>
        <h2>
          Processing shortcut items
        </h2>
        <p>
          To <dfn>process a shortcut</dfn>, given [=ordered map=] |item:ordered
          map| and |scope:URL|,:
        </p>
        <ol class="algorithm">
          <li>Return failure if it's the case that:
            <ul>
              <li>|item| is not [=ordered map=].
              </li>
              <li>|item|["name"] doesn't [=map/exist=].
              </li>
              <li>|item|["name"] is the empty string.
              </li>
              <li>|item|["url"] doesn't [=map/exist=].
              </li>
              <li>|item|["url"] is not a [=string=].
              </li>
            </ul>
          </li>
          <li>Let |url:URL| be the result of [=URL Parser|parsing=]
          |item|["url"] with |manifest URL| as the base URL.
          </li>
          <li>If |url| is failure, return failure.
          </li>
          <li>If |url| is not [=manifest/within scope=] of |scope|, return
          failure.
          </li>
          <li>Let |shortcut:ordered map| be |ordered map| «[ "url" → |url|,
          "name" → |item|["name"] ]».
          </li>
          <li>[=Process image resources=] passing |item|["icons"], |shortcut|,
          |manifest URL|, and "icons".
          </li>
          <li>Return |shortcut|.
          </li>
        </ol>
      </section>
    </section>
    <section>
      <h2>
        External application resource
      </h2>
      <aside class="issue atrisk" data-number="956"></aside>
      <p>
        Each <dfn data-local-lt="external application resource's">external
        application resource</dfn> represents an application related to the web
        application.
      </p>
      <p>
        An [=external application resource=] can have the following members,
        some of which are required to be a [=valid external application
        resource=]:
      </p>
      <ul>
        <li>[=external application resource/fingerprints=] member
        </li>
        <li>[=external application resource/id=] member
        </li>
        <li>[=external application resource/min_version=] member
        </li>
        <li>[=external application resource/platform=] member
        </li>
        <li>[=external application resource/url=] member
        </li>
      </ul>
      <p>
        A <dfn>valid external application resource</dfn> MUST have [=external
        application resource/platform=] member, and either an [=external
        application resource/url=] or an [=external application resource/id=]
        member (or both).
      </p>
      <aside class="example">
        <p>
          In the following example, the web application is listing two
          different related applications, one on Google Play Store and the
          other one on the iTunes Store. The one on the Google Play Store has
          an Android package name, a minimum version specifier, and
          cryptographic fingerprints used for verification, in a
          Play-Store-specific manner.
        </p>
        <pre class="json">
          {
            "related_applications": [
              {
                "platform": "play",
                "url": "https://play.google.com/store/apps/details?id=com.example.app1",
                "id": "com.example.app1",
                "min_version": "2",
                "fingerprints": [
                  {
                    "type": "sha256_cert",
                    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2"
                  }
                ]
              },
              {
                "platform": "itunes",
                "url": "https://itunes.apple.com/app/example-app1/id123456789"
              }
            ]
          }
        </pre>
      </aside>
      <section>
        <h3>
          `platform` member
        </h3>
        <p>
          The <code><dfn data-dfn-for=
          "external application resource">platform</dfn></code> member
          represents the [=platform=] this [=external application resource=] is
          associated with. A <dfn data-dfn-for="">platform</dfn> represents a
          software distribution ecosystem or possibly an operating system. This
          specification does not define the particular values for the
          <a>platform</a> member.
        </p>
        <aside class="Platforms registry">
          The working group maintains a <a href=
          "https://github.com/w3c/manifest/wiki/Platforms">registry of known
          platform values</a>.
        </aside>
      </section>
      <section>
        <h3>
          `url` member
        </h3>
        <p>
          An [=external application resource's=] <code><dfn data-dfn-for=
          "external application resource">url</dfn></code> member is the
          <a>URL</a> where the application can be found.
        </p>
        <p>
          To <dfn>process the `url` member of an application</dfn>:
        </p>
        <ol class="algorithm">
          <li>If <var>application URL</var> is missing, return null.
          </li>
          <li>Otherwise, [=URL Parser|parse=] <var>application URL</var> and if
          the result is not failure, return the result. Otherwise return null.
          </li>
        </ol>
      </section>
      <section>
        <h3>
          `id` member
        </h3>
        <p>
          An [=external application resource's=] <code><dfn data-dfn-for=
          "external application resource">id</dfn></code> member represents the
          id which is used to represent the application on the platform.
        </p>
      </section>
      <section>
        <h3>
          `min_version` member
        </h3>
        <p>
          An [=external application resource's=] <code><dfn data-dfn-for=
          "external application resource">min_version</dfn></code> member
          represents the minimum version of the application that is considered
          related to this web app. This version is a <a>string</a> with
          platform-specific syntax and semantics.
        </p>
      </section>
      <section>
        <h3>
          `fingerprints` member
        </h3>
        <p>
          An [=external application resource's=] <code><dfn data-dfn-for=
          "external application resource">fingerprints</dfn></code> member
          represents an [=list=] of [=fingerprints=].
        </p>
        <p>
          A <dfn data-local-lt="fingerprints">fingerprint</dfn> represents a
          set of cryptographic fingerprints used for verifying the application.
          A fingerprint has the following two members: <dfn data-dfn-for=
          "fingerprint">type</dfn> and <dfn data-dfn-for=
          "fingerprint">value</dfn>. Each of these are <a>string</a>s, but
          their syntax and semantics are platform-defined.
        </p>
      </section>
    </section>
    <section>
      <h2>
        Installable web applications
      </h2>
      <p>
        A common use case of a manifest is for a user agent to
        <dfn data-local-lt="installing|installation" data-lt=
        "installed">install</dfn> a web application; whereby the user agent
        provides the end-user with a means of instantiating a new <a>top-level
        browsing context</a> that has the manifest's members <a>applied</a> to
        it. A web application that is installed is known as a <dfn data-export=
        "">installed web application</dfn>. That is, the manifest's members, or
        their defaults, are in effect on the <a>top-level browsing context</a>.
        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 <a>applied</a> to it.
      </p>
      <p class="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. When [=launching a web application=], the manifest is
        <a>applied</a> by the user agent to the <a>top-level browsing
        context</a> prior to the <a>start URL</a> being loaded. This gives the
        user agent an opportunity to apply the relevant values of the manifest,
        possibly changing the <a>display mode</a> and screen orientation of the
        web application. Alternatively, and again as an example, the user agent
        could <a>install</a> the web application into a list of bookmarks
        within the user agent itself.
      </p>
      <section>
        <h3>
          Application's name
        </h3>
        <p>
          The <dfn>application's name</dfn> is derived from either the
          [=manifest/name=] member or [=manifest/short_name=] member.
        </p>
        <p>
          When either the [=manifest/name=] member or the
          [=manifest/short_name=] member is missing, empty, or the wrong type,
          a user agent MAY use the [=manifest/name=] member as a fallback for
          the [=manifest/short_name=] member or [=manifest/short_name=] member
          as the fallback for the [=manifest/name=] member.
        </p>
        <p>
          If the [=manifest/name=] and [=manifest/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 [=manifest/name=]
          or [=manifest/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 <a>application's name</a>.
        </p>
        <p>
          When both the [=manifest/name=] and [=manifest/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
          [=manifest/short_name=] member might be better suited for the space
          available underneath an icon).
        </p>
      </section>
      <section>
        <h3>
          Launching a web application
        </h3>
        <p>
          At the discretion of the operating system or user agent, run the
          steps to [=launch a web application=] with a [=Document/processed
          manifest=].
        </p>
        <p class="note">
          This would typically take place when the user selects an
          [=installed=] web app from an app launching UI surface e.g., a home
          screen, launcher or start menu.
        </p>
        <p>
          The steps to <dfn data-lt="launching a web application" data-export=
          "">launch a web application</dfn> is given by the following
          algorithm. The algorithm takes a [=Document/processed manifest=]
          |manifest:processed manifest|, an optional [=URL=] |target URL:URL|,
          an optional [=POST resource=] |POST resource| and returns an
          [=application context=].
        </p>
        <p>
          |target URL|, if given, MUST be [=manifest/within scope=] of
          |manifest|.
        </p>
        <p>
          Other specifications MAY replace this algorithm's steps with their
          own steps. This replacement will take effect for all invocations of
          [=launch a web application=].
        </p>
        <p class="note">
          This algorithm is replaceable to allow an experimental <a href=
          "https://github.com/WICG/web-app-launch">launch_handler</a> manifest
          field to configure the behavior of all web application launches. The
          replacement algorithm invokes [=create a new application context=] by
          default but under certain conditions behaves differently.
        </p>
        <ol class="algorithm">
          <li>Return the result of running the steps to [=create a new
          application context=] passing |manifest|, |target URL| and |POST
          resource|.
          </li>
        </ol>
        <p>
          The steps to <dfn data-export="">create a new application
          context</dfn> is given by the following algorithm. The algorithm
          takes a [=Document/processed manifest=] |manifest:processed
          manifest|, an optional [=URL=] |target URL:URL|, an optional [=POST
          resource=] |POST resource| and returns an [=application context=].
        </p>
        <ol class="algorithm">
          <li>If |target URL| was not given, set |target URL| to [=start URL=].
          </li>
          <li>Let |traversable| be the result of running the steps to [=create
          a fresh top-level traversable=] with |target URL| and |POST
          resource|.
          </li>
          <li>Let |browsing context| be the |traversable|'s <a data-cite=
          "html#nav-bc">active browsing context</a>.
          </li>
          <li>[=Apply=] |manifest| to |browsing context|.
          </li>
          <li>Return |browsing context|.
          </li>
        </ol>
      </section>
      <section>
        <h3 id="installation-sec">
          Privacy and security considerations
        </h3>
        <p>
          It is RECOMMENDED that UI that affords the end user the ability to
          <a>install</a> a web application also allows inspecting the icon,
          name, <a>start URL</a>, 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.
        </p>
        <p>
          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 <a>installed</a> - or by using an entirely different
          cache from that used for regular web browsing.
        </p>
      </section>
      <section>
        <h3>
          Uninstallation
        </h3>
        <p>
          User agents SHOULD provide a mechanism for the user to remove an
          <a>installed web application</a> application.
        </p>
        <p>
          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.
        </p>
      </section>
    </section>
    <section id="nav-scope">
      <h2>
        Navigation scope
      </h2>
      <p>
        The <dfn data-dfn-for="manifest" data-lt="navigation scope"
        data-export="">navigation scope of a manifest</dfn> is the "scope" item
        of a [=Document/processed manifest=]. The navigation scope restricts
        the set of URLs to which an [=application context=] can be
        [=navigated=] while the manifest is [=applied=].
      </p>
      <div class="note">
        <p>
          If the [=manifest/scope=] member is not present in the manifest, it
          defaults to the parent path of the [=manifest/start_url=] member. For
          example, if [=manifest/start_url=] is `/pages/welcome.html`, and
          [=manifest/scope=] is missing, the navigation scope will be `/pages/`
          on the same origin. If [=manifest/start_url=] is `/pages/` (the
          trailing slash is important!), the navigation scope will be
          `/pages/`.
        </p>
        <p>
          Developers should take care, if they rely on the default behavior,
          that all of the application's page URLs begin with the parent path of
          the start URL. To be safe, explicitly specify [=manifest/scope=].
        </p>
      </div>
      <p>
        A [=URL=] |target:URL| is said to be <dfn data-dfn-for="URL"
        data-export="">within scope</dfn> of [=URL=] |scope:URL| if the
        following algorithm returns `true`:
      </p>
      <ol class="algorithm">
        <li>If |target| and |scope| are not [=same origin=], return `false`.
        </li>
        <li>Let |scopePath:string| be the [=string/concatenation=] of
        |scopes|'s [=URL/path=] using U+002F (/) as the separator.
        </li>
        <li>Let |targetPath:string| be the [=string/concatenation=] of
        |target|'s [=URL/path=] using U+002F (/) as the separator.
        </li>
        <li>Return a [=boolean=] indicating whether |targetPath| starts with
        |scopePath:string|.
        </li>
      </ol>
      <p>
        A [=URL=] |target:URL| is <dfn data-dfn-for="manifest" data-lt=
        "within scope" data-export="">within scope</dfn> of a
        |manifest:processed manifest| if the |target| is [=URL/within scope=]
        of |manifest|'s [=manifest/navigation scope=] (i.e., [=URL/within
        scope=] of |manifest|'s [=manifest/scope=] member).
      </p>
      <aside class="note" title="Scope is a simple string match">
        <p>
          The URL string matching in this algorithm is prefix-based rather than
          path-structural (e.g. a target URL string `/prefix-of/resource.html`
          will match an app with scope `/prefix`, even though the path segment
          name is not an exact match). This is intentional for consistency with
          <a data-cite="SERVICE-WORKERS-1#scope-match-algorithm">Service
          Workers</a>. To avoid unexpected behavior, use a scope ending in a
          `/`.
        </p>
      </aside>
      <p>
        If the [=application context=]'s [=navigable/active document=]'s
        [=Document/URL=] is not [=manifest/within scope=] of the [=application
        context=]'s [=Document/processed manifest=], the user agent SHOULD show
        a prominent UI element indicating the [=Document/URL=] or at least its
        [=origin=], including whether it is served over a secure connection.
        This UI SHOULD differ from any UI used when the [=Document/URL=] is
        [=manifest/within scope=] of the [=application context=]'s
        [=Document/processed manifest=], in order to make it obvious that the
        user is navigating off scope.
      </p>
      <aside class="note">
        <p>
          Nothing prevents an <a>application context</a> from navigating to a
          <a>URL</a> that is outside of the manifest's [=manifest/navigation
          scope=], while still having the <a>manifest</a> <a>applied</a> to it.
        </p>
        <p>
          Unlike previous versions of this specification, user agents are no
          longer required or allowed to block off-scope navigations, or open
          them in a new <a>top-level browsing context</a>. This practice broke
          some sites that navigate to an off-scope URL (e.g., to perform
          third-party authentication). See <a href=
          "https://github.com/w3c/manifest/issues/646">Issue 646</a>.
        </p>
      </aside>
      <section class="informative">
        <h3 id="navigation-scope-security-considerations">
          Security considerations
        </h3>
        <p>
          The above recommendation (to show some UI when the <a>application
          context</a> is navigated to an out-of-scope <a>URL</a>) is for
          security reasons. It ensures that users are always aware of which
          <a>origin</a> they are interacting with.
        </p>
        <p>
          Despite this, there is still a potential spoofing risk, if an
          installed app pretends to navigate to an out-of-scope site on another
          <a>origin</a>. The site shows a fake version of the user agent's
          prominent out-of-scope UI, indicating to the user that it is on
          another origin. However, in reality, the user has never navigated
          away from the installed app's origin, and the user agent is not
          showing any out-of-scope UI. User agents could try to show the
          out-of-scope UI in a way that cannot be spoofed by the installed app.
          However, due to the nature of the user agent's UI being minimal or
          non-existent for installed apps, this may not be possible.
        </p>
      </section>
      <section>
        <h3>
          Deep links
        </h3>
        <p>
          A <dfn>deep link</dfn> is a URL that is [=manifest/within scope=] of
          an [=installed web application=]'s [=Document/processed manifest=].
        </p>
        <p>
          An <a>application context</a> can be instantiated through a <a>deep
          link</a>, in which case, the manifest is applied and the <a>deep
          link</a> is loaded within the context of a web application.
        </p>
        <aside class="note">
          <p>
            The concept of a <a>deep link</a> is useful in that it allows
            hyperlinking from one <a>installed web application</a> to another.
            This can be from a native application to an <a>installed web
            application</a> and vice versa. Theoretically, this can provide
            seamless context switching between native and web applications
            through standard hyperlinks. And in the case where a particular web
            application is not <a>installed</a>, the OS can just open the link
            in the user's preferred web browser.
          </p>
          <p>
            Implementers are encouraged make such context switching obvious to
            the user, for example, by adhering to the human interface
            guidelines of the underlying platform with respect to application
            switching.
          </p>
        </aside>
      </section>
    </section>
    <section>
      <h2>
        Choosing a display mode
      </h2>
      <p>
        A [=display mode=], as defined in [[MEDIAQUERIES-5]], 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.
      </p>
      <p>
        Once a user agent [=applies=] a particular <a>display mode</a> to an
        <a>application context</a>, it becomes the <dfn>default display
        mode</dfn> for the <a>top-level browsing context</a> (i.e., it is used
        as the display mode when the window is <a>navigated</a>). The user
        agent MAY override the <a>default display mode</a> for security reasons
        (e.g., the <a>top-level browsing context</a> is <a>navigated</a> to
        another origin) and/or the user agent MAY provide the user with a means
        of switching to another <a>display mode</a>.
      </p>
      <p>
        When the [=manifest/display=] member is missing, or if there is no
        valid [=manifest/display=] member, the user agent uses the [=display
        mode/browser=] <a>display mode</a> as the <a>default display mode</a>.
        As such, the user agent MUST support the [=display mode/browser=]
        <a>display mode</a>.
      </p>
      <p>
        Every [=display mode=] has a <dfn>fallback chain</dfn>, which is a list
        of [=display modes=]. The [=fallback chain=] for:
      </p>
      <ol>
        <li>[=display mode/browser=] is «».
        </li>
        <li>[=display mode/minimal-ui=] is « "[=display mode/browser=]" ».
        </li>
        <li>[=display mode/standalone=] is « "[=display mode/minimal-ui=]",
        "[=display mode/browser=]" ».
        </li>
        <li>[=display mode/fullscreen=] is « "[=display mode/standalone=]",
        "[=display mode/minimal-ui=]", "[=display mode/browser=]" ».
        </li>
      </ol>
      <p>
        The <dfn>steps for determining the web app's chosen display mode</dfn>
        is given by the following algorithm. The algorithm takes a
        [=Document/processed manifest=] |manifest:processed manifest| and
        returns a [=display mode=].
      </p>
      <ol class="algorithm">
        <li>[=application manifest/processing extension-point=]: process any
        proprietary and/or other supported display modes at this point in the
        algorithm.
        </li>
        <li>If the user agent supports |manifest|["display"], then return
        |manifest|["display"].
        </li>
        <li>[=list/For each=] |fallback_mode| of the [=fallback chain=] of
        |manifest|["display"]:
          <ol>
            <li>If the user agent supports the |fallback_mode|, then return
            |fallback_mode|.
            </li>
          </ol>
        </li>
      </ol>
      <p class="note">
        The above loop is guaranteed to return a value before the assertion,
        due to the fact that [=display mode/browser=] is in every mode's
        [=fallback chain=], and the requirement that all user agents support
        the [=display mode/browser=] [=display mode=].
      </p>
      <aside class="example">
        <p>
          SuperSecure Browser (a fictitious browser) only supports the
          `minimal-ui` and `browser` display modes, but a developer declares
          that they wants `fullscreen` in the manifest by using the
          [=manifest/display=] property. In this case, the user agent will
          first check if it supports `fullscreen` (it doesn't), so it falls
          back to `standalone` (which it also doesn't support), and ultimately
          falls back to `minimal-ui`.
        </p>
      </aside>
      <p>
        The <dfn>display modes list</dfn> is the [=list=] « "[=display
        mode/fullscreen=]", "[=display mode/standalone=]", "[=display
        mode/minimal-ui=]", "[=display mode/browser=]" ».
      </p>
      <p>
        A user agent MUST reflect the applied <a>display mode</a> of the web
        application in the '`display-mode`' media feature [[MEDIAQUERIES-5]].
      </p>
      <p class="note">
        A user agent will 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 application into
        fullscreen, then the user agent would reflect this change to CSS and
        scripts via the '`display-mode`' media feature.
      </p>
    </section>
    <section id="priv-sec">
      <h2>
        Privacy and security considerations
      </h2>
      <p>
        This specification does not directly deal with high-value data.
        However, <a>installed web applications</a> and their data could be seen
        as "high value" (particularly from a privacy perspective).
      </p>
      <p>
        As the manifest format is JSON and will commonly be encoded using
        [[UNICODE]], the security considerations described in [[JSON]] and
        [[UNICODE-SECURITY]] apply. In addition, because there is no way to
        prevent developers from including custom/unrestrained data in a
        <a>manifest</a>, implementors need to impose their own
        implementation-specific limits on the values of otherwise unconstrained
        member types, e.g. to prevent denial of service attacks, to guard
        against running out of memory, or to work around platform-specific
        limitations.
      </p>
      <p>
        Web applications will generally contain ECMAScript, HTML, CSS files,
        and other media, which are executed in a sand-boxed environment. As
        such, implementors need to be aware of the security implications for
        the types they support. Specifically, implementors need to consider the
        security implications outlined in at least the following
        specifications: [[CSS-MIME]], [[ECMAScript-MIME]], [[HTML]].
      </p>
      <p>
        As web applications can contain content that is able to simultaneously
        interact with the local device and a remote host, implementors need to
        consider the privacy implications resulting from exposing private
        information to a remote host. Mitigation and in-depth defensive
        measures are an implementation responsibility and not prescribed by
        this specification. However, in designing these measures, implementors
        are advised to enable user awareness of information sharing, and to
        provide easy access to interfaces that enable revocation of
        permissions.
      </p>
      <p>
        As this specification allows for the declaration of URLs within certain
        members of a manifest, implementors need to consider the security
        considerations discussed in the [[URL]] specification. Implementations
        intending to display <abbr title=
        "Internationalized Resource Identifiers">IRIs</abbr> and <abbr title=
        "Internationalized domain name">IDNA</abbr> addresses found in the
        manifest are strongly encouraged to follow the security advice given in
        [[UNICODE-SECURITY]].
      </p>
      <p>
        Developers need to be aware of the security considerations discussed
        throughout the [[CSP3]] specification, particularly in relation to
        making `data:` a valid source for the purpose of <q>inlining</q> a
        manifest. Doing so can enable XSS attacks by allowing a manifest to be
        included directly in the document itself; this is best avoided
        completely.
      </p>
      <p>
        It is RECOMMENDED that UI that affords the end user the ability to
        <a>install</a> a web application also allows inspecting the icon, name,
        <a>start URL</a>, 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.
      </p>
      <p>
        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
        <a>installed</a> - or by using an entirely different cache from that
        used for regular web browsing.
      </p>
      <p>
        It's conceivable that a shortcut [=shortcut item/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 [=shortcut item/url=] that
        uniquely identify the user (e.g., a server assigned <abbr>UUID</abbr>).
        This is fingerprinting/privacy sensitive information that the user
        might not be aware of.
      </p>
      <p>
        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.
      </p>
      <p>
        Additionally, when applying a manifest that sets the <a>display
        mode</a> to anything except "[=display mode/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".
      </p>
      <p>
        The `display` member 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.
      </p>
    </section>
    <section class="appendix">
      <h2>
        IANA considerations
      </h2>
      <p>
        The mime type <code><dfn data-export=
        "">application/manifest+json</dfn></code> is the <dfn data-export=
        "">application manifest media type</dfn>. Both the mime type and the
        `.webmanifest` file extension are <a href=
        "https://www.iana.org/assignments/media-types/application/manifest+json">
        registered</a> with the Internet Assigned Numbers Authority
        (<abbr title="Internet Assigned Numbers Authority">IANA</abbr>).
      </p>
      <section>
        <h3>
          Media type registration
        </h3>
        <p>
          If the protocol over which the manifest is transferred supports the
          [[MIME-TYPES]] specification (e.g. HTTP), it is RECOMMENDED that the
          manifest be labeled with the [=application manifest media type=].
        </p>
        <dl>
          <dt>
            Type name:
          </dt>
          <dd>
            application
          </dd>
          <dt>
            Subtype name:
          </dt>
          <dd>
            manifest+json
          </dd>
          <dt>
            Required parameters:
          </dt>
          <dd>
            N/A
          </dd>
          <dt>
            Optional parameters:
          </dt>
          <dd>
            N/A
          </dd>
          <dt>
            Encoding considerations:
          </dt>
          <dd>
            Same as for application/json ([[RFC7159]] section 8.1)
          </dd>
          <dt>
            Privacy and security considerations:
          </dt>
          <dd>
            See [[[#priv-sec]]].
          </dd>
          <dt>
            Applications that use this MIME type:
          </dt>
          <dd>
            Web browsers
          </dd>
          <dt>
            Additional information:
          </dt>
          <dd>
            <dl>
              <dt>
                Magic number(s):
              </dt>
              <dd>
                N/A
              </dd>
              <dt>
                File extension(s):
              </dt>
              <dd>
                .webmanifest
              </dd>
              <dt>
                Macintosh file type code(s):
              </dt>
              <dd>
                TEXT
              </dd>
            </dl>
          </dd>
          <dt>
            Person & email address to contact for further information:
          </dt>
          <dd>
            The <a href="https://www.w3.org/2019/webapps/" rel="nofollow">Web
            Applications Working Group</a> can be contacted at <a href=
            "https://lists.w3.org/Archives/Public/public-webapps/" rel=
            "nofollow">public-webapps@w3.org</a>.
          </dd>
          <dt>
            Intended usage:
          </dt>
          <dd>
            COMMON
          </dd>
          <dt>
            Restrictions on usage:
          </dt>
          <dd>
            none
          </dd>
          <dt>
            Author:
          </dt>
          <dd>
            W3C's Web Applications Working Group.
          </dd>
          <dt>
            Change controller:
          </dt>
          <dd>
            W3C.
          </dd>
        </dl>
      </section>
      <section>
        <h3>
          Link relation type registration
        </h3>
        <dl>
          <dt>
            Relation Name:
          </dt>
          <dd>
            manifest
          </dd>
          <dt>
            Description:
          </dt>
          <dd>
            Links to a <a>manifest</a>. A manifest provides developers with a
            centralized place to put metadata associated with a web
            application.
          </dd>
          <dt>
            Reference:
          </dt>
          <dd>
            <a href=
            "https://www.w3.org/TR/appmanifest/">https://www.w3.org/TR/appmanifest/</a>
          </dd>
          <dt>
            Notes:
          </dt>
          <dd>
            See link type "manifest" for details about how a web manifest is
            [=fetched=] [=processing a manifest|processed=].
          </dd>
        </dl>
      </section>
    </section>
    <section id="conformance" class="appendix">
      <p>
        There is only one class of product that can claim conformance to this
        specification: a [=user agent=].
      </p>
      <p class="note">
        Although this specification is primarily targeted at web browsers, it
        is feasible that other software could also implement this specification
        in a conforming manner. For instance, search engines, or crawlers,
        could find and process manifests to build up catalogs of sites that
        potentially work as installable web applications.
      </p>
      <section class="informative">
        <h3>
          Extensibility
        </h3>
        <p>
          This specification is designed to be extensible. Other specifications
          are encouraged to define new members for the manifest. However, in
          doing so, please follow the conventions used in this specification.
          In particular, use the [=application manifest/processing
          extension-point=] to hook into the steps for <a>processing a
          manifest</a>. Also, be sure to specify the steps for processing your
          particular member in the manner set forth in this specification. This
          will help keep this part of the platform consistent.
        </p>
        <p>
          To allow the community to easily find extensions, please add your
          extensions to the <a href=
          "https://github.com/w3c/manifest/wiki/Extensions-Registry">Extensions
          Registry</a>.
        </p>
        <p>
          When specifying a new member, don't override or <a href=
          "https://annevankesteren.nl/2014/02/monkey-patch">monkey patch</a>
          anything defined in this specification. Also, don't assume your
          member will be processed before or after any other member. Keep your
          new member, and its processing, atomic and self contained. Note also
          that implementations are free to ignore any member they do not
          recognize or support.
        </p>
        <p>
          If you are writing a specification and temporarily want to patch this
          specification to help implementations along, <a href=
          "https://github.com/w3c/manifest/issues">file a bug</a> so the
          community is informed of what you are trying to do.
        </p>
        <section id="proprietary-extensions" class="informative">
          <h3>
            Proprietary manifest members
          </h3>
          <p>
            Although proprietary extensions are undesirable, they can't
            realistically be avoided. 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.
          </p>
          <p>
            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 (see [[[#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.
          </p>
          <p>
            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.
          </p>
          <p>
            We encourage implementors to add proprietary extensions to our
            <a href=
            "https://github.com/w3c/manifest/wiki/Extensions-Registry">Extensions
            Registry</a>. 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.
          </p>
          <p>
            The following is an example of three hypothetical proprietary
            extensions.
          </p>
          <pre class="example json" title="Proprietary extensions">
            {
              ...
              "kpl_fancy_feature": "some/url/img",
              "gmpc_awesome_thing": { ... },
              "blitzly_site_verification": "KEY_9864D0966935"
              ...
            }
          </pre>
          <p class="note">
            In this example, we have deliberately chosen (made-up) names of
            things that could be external sites or services, <em>not</em> names
            of browsers or browser vendors. These are not vendor prefixes
            belonging to the browser that invented them; they are prefixes of
            proprietary services.
          </p>
        </section>
      </section>
    </section>
    <section class="appendix informative">
      <h2 id="incubations">
        Incubations
      </h2>
      <p>
        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:
      </p>
      <dl>
        <dt>
          `BeforeInstallPrompt` and `window.onappinstalled` event
        </dt>
        <dd>
          The `BeforeInstallPrompt` event and `window.onappinstalled` event
          were originally part of this specification. However, they were
          <a href="https://github.com/w3c/manifest/pull/836">removed from the
          specification</a> because they did not have support from two or more
          implementers. You can now find them in the <a href=
          "https://github.com/WICG/manifest-incubations">`BeforeInstallPrompt`
          event and `window.onappinstalled` repository</a> at the <a href=
          "https://wicg.io"><abbr title=
          "Web Incubator Community Group">WICG</abbr></a>.
        </dd>
        <dt>
          `share_target` member
        </dt>
        <dd>
          The `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 <a href=
          "https://wicg.github.io/web-share-target/">Web Share Target</a>
          specification, being incubated at the <a href=
          "https://wicg.io">WICG</a>.
        </dd>
      </dl>
    </section>
    <section class="appendix informative">
      <h2>
        Application Information
      </h2>
      <p>
        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
        [[[manifest-app-info]]]:
      </p>
      <ul>
        <li>`categories`
        </li>
        <li>`description`
        </li>
        <li>`iarc_rating_id`
        </li>
        <li>`screenshots`
        </li>
      </ul>
    </section>
    <section class="appendix informative">
      <h2>
        Relationship to HTML's `link` and `meta` elements
      </h2>
      <p>
        An extensive discussion of why we chose to use JSON instead of HTML
        `meta`/`link` tags for this specification is available on <a href=
        "https://github.com/w3c/manifest/issues/97">GitHub</a> and on the
        <a href=
        "https://lists.w3.org/Archives/Public/www-tag/2014Jan/0139.html">www-tag</a>
        list. Below is a short summary of the key points raised in those
        discussions.
      </p>
      <p>
        The document format defined in this specification provides a unified
        means of encapsulating metadata about a Web application in a way that
        we hope will avoid existing pitfalls with both proprietary and
        [[HTML]]'s `meta`/`link` tags. Those pitfalls include:
      </p>
      <ul>
        <li>Developers have to duplicate the icons and application name in each
        page of a web site, leading to significant redundancy across pages.
        This is compounded if that information never gets used by the user
        agent (e.g., the user never bookmarks the web application).
        </li>
        <li>Spreading metadata across multiple documents can cause data to fall
        out of sync.
        </li>
        <li>If the metadata for a web application lives in a HTML document,
        that significantly increases the cost to user agents (and users) of
        checking for updates to the metadata of a site. Since the HTML file is
        likely to change often, it means that a user agent will often have to
        download the whole HTML file in order to check if any of the relevant
        meta tags have changed. If this resource contains inlined resources
        like JavaScript, images, or stylesheets, this could be a non-trivial
        download.
        </li>
      </ul>
      <p>
        Although it would be unrealistic to think that this specification won't
        bring its own set of problems, externalizing this data in the form of a
        manifest solves the problems described above. These problems are solved
        by:
      </p>
      <ul>
        <li>Making the manifest externally linkable: External manifest files
        can be cached as external resources, saving both bytes and redundancy
        in the markup.
        </li>
        <li>Flexible value types: unlike HTML attributes, members of the
        manifest can represent data using complex types, such as objects and
        arrays, rather than just strings. This solves the problem of the
        awkward and highly inconsistent formats the values of proprietary
        `meta` tags are currently using, especially when a tag's value contains
        several sub-values.
        </li>
      </ul>
      <p>
        In addition, standardizing the functionality currently provided by the
        various `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 <cite><a href=
        "https://w3c-webmob.github.io/installable-webapps/">Use Cases and
        Requirements for Installable Web Apps</a></cite> .
      </p>
      <p>
        Lastly, this specification does not make the standardized solutions
        found in [[HTML]] redundant. When members like the `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).
      </p>
    </section>
    <section class="appendix informative">
      <h2>
        JSON Schema
      </h2>
      <p>
        Developers interested in validating <a>manifest</a> documents can find
        an unofficial <a href="https://json.schemastore.org/web-manifest">JSON
        schema for the manifest format</a> at <a href=
        "https://schemastore.org/json/">schemastore.org</a>. It is licensed
        under <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache
        2.0</a>. It is kindly maintained by <a href=
        "https://github.com/madskristensen">Mads Kristensen</a>. If you find
        any issues with the JSON schema, please <a href=
        "https://github.com/SchemaStore/schemastore/issues/">file a bug</a> at
        the <a href="https://github.com/SchemaStore/schemastore">SchemaStore
        repository</a> on GitHub.
      </p>
      <aside class="note" title="Web Manifest JSON Schema">
        <details>
          <summary>
            Click to view schema.
          </summary>
          <pre class="json" data-include=
          "https://json.schemastore.org/web-manifest"></pre>
        </details>
      </aside>
    </section>
    <section id="internationalization" class="appendix informative">
      <h2>
        Internationalization
      </h2>
      <p>
        It is expected that authors will localize the content of a manifest by
        using one of the following options:
      </p>
      <dl>
        <dt>
          Dynamically setting the language:
        </dt>
        <dd>
          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").
        </dd>
        <dt>
          Using content-negotiation, or geotargeting, etc. on the server:
        </dt>
        <dd>
          The server that hosts the web application could attempt to
          predetermine the end-user's language by using <a href=
          "https://en.wikipedia.org/wiki/Geotargeting">geotargeting</a> or by
          using content negotiation (e.g., using [[RFC7540]]'s
          "`Accept-Language`" header, or even a custom HTTP header).
        </dd>
      </dl>
      <p>
        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]].
      </p>
    </section>
    <section>
      <h2>
        Use Cases and Requirements
      </h2>
      <p>
        This document attempts to address the <cite><a href=
        "https://w3c-webmob.github.io/installable-webapps/">Use Cases and
        Requirements for Installable Web Apps</a></cite>.
      </p>
    </section>
    <section id="issue-summary"></section>
    <section class="informative">
      <h2>
        Change log
      </h2>
      <p>
        The following are some significant changes that were made since First
        Public Working Draft:
      </p>
      <script class="remove">
        const ignoredHashes = [
          "c0e3654ec18d04452c079c9839909c9a7295f2f7"
        ];
        function removeCommits(entry) {
          const { message, hash } = entry;
          for (const ignoredHash of ignoredHashes) {
            if (ignoredHash.startsWith(hash)) {
              return false;
            };
          }
          return !/^editorial|^chore|^\[chore|^fix|^refactor|^tests?|^docs|^typo|^nit/i.test(message);
        }
      </script> <rs-changelog from="fef12b3e313bb61d9434da73dc565132d8f4c483"
      filter="removeCommits"></rs-changelog>
    </section>
    <section class="appendix informative">
      <h2>
        Acknowledgements
      </h2>
      <p>
        This document reuses text from the [[HTML]] specification, as permitted
        by the license of that specification.
      </p>
      <p>
        Dave Raggett and Dominique Hazael-Massieux contributed to this
        specification via the HTML5Apps project.
      </p>
      <p>
        Claudio Gomboli for icon example images.
      </p>
      <p>
        Indiana University Bloomington security researchers have contributed to
        this specification by reporting potential risks related to out-of-scope
        navigation.
      </p>
    </section>
    <section id="index"></section>
  </body>
</html>