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: "Rob Dolin",
          company: "Microsoft Corporation",
          companyURL: "https://www.microsoft.com/en-us/",
        },
      ],
      editors: [
        {
          name: "Marcos Cáceres",
          company: "W3C",
          companyURL: "https://www.w3.org",
          w3cid: 39125,
        },
        {
          name: "Kenneth Rohde Christiansen",
          company: "Intel Corporation",
          companyURL: "https://intel.com/",
          w3cid: 57705,
        },
        {
          name: "Mounir Lamouri",
          company: "Google Inc.",
          companyURL: "https://www.google.com/",
          w3cid: 45389,
        },
        {
          name: "Anssi Kostiainen",
          company: "Intel Corporation",
          companyURL: "https://intel.com/",
          w3cid: 41974,
        },
        {
          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,
        },
      ],
      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-dfn-for="" data-lt=
        "application manifest|manifest's">manifest</dfn> is a [[JSON]] document
        that contains startup parameters and application defaults for when a
        web application is launched.
      </p>
      <p>
        As a manifest is JSON, this specification relies on the types defined
        in [[JSON]] specification: namely <dfn data-no-export="">object</dfn>,
        <dfn data-no-export="">array</dfn>, <dfn data-no-export=
        "">string</dfn>, and <dfn data-no-export="">boolean</dfn>. Strict type
        checking is not enforced by this specification. Instead, each member's
        definition specifies the steps required to process a particular member
        and what to do when a type does not match what is expected.
      </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/lang=]
        </li>
        <li>[=manifest/name=]
        </li>
        <li>[=manifest/orientation=]
        </li>
        <li>[=manifest/prefer_related_applications=]
        </li>
        <li>[=manifest/protocol_handlers=]
        </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": "/",
              "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 official file extension for the manifest is `.webmanifest`.
            Some web servers recognize this extension and transfer the file
            using the standardized <a>application manifest MIME 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
          one of the <a>text-direction values</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-direction values</dfn> are the following, implying that
          the value of the <a>localizable members</a> is by default:
        </p>
        <dl>
          <dt>
            "<dfn>ltr</dfn>"
          </dt>
          <dd>
            Left-to-right text.
          </dd>
          <dt>
            "<dfn>rtl</dfn>"
          </dt>
          <dd>
            Right-to-left text.
          </dd>
          <dt>
            "<dfn>auto</dfn>" (default)
          </dt>
          <dd>
            No explicit directionality.
          </dd>
        </dl>
        <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 <a>ltr</a> or <a>rtl</a>,
          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
          <a>ltr</a>, or 1 if the <a>base direction</a> is <a>rtl</a>.
          </li>
          <li>Otherwise the <a>base direction</a> is "[=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 [=object=] |json:JSON|
          and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["dir"] is not [=string=], or if
          |json|["dir"] doesn't match one of the [=text-direction values=],
          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 [=object=] |json:JSON|
          and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["lang"] is not [=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 [=object=]
          |json:JSON| 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
          one of the <a>display modes values</a>.
        </p>
        <p>
          To <dfn>process the `display` member</dfn>, given [=object=]
          |json:JSON| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["display"] is not [=string=], return.
          </li>
          <li>If |json|["display"] doesn't match one of the [=display modes
          values=], 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 display modes <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 JSON
          |json:JSON| and [=ordered map=] |manifest:ordered map|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["orientation"] is not [=string=], return.
          </li>
          <li>If |json|["orientation"] doesn't match one 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 [=object=]
          |json:JSON|, [=ordered map=] |manifest:ordered map|, [=URL=]
          |manifest URL:URL|, and [=URL=] |document URL:URL|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["start_url"] is not [=string=], return.
          </li>
          <li>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 <var>document
          URL</var>, 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>
        </section>
      </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
          [=object=] |json:JSON| 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 the type of |json|["related_applications"] is not [=array=],
          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 [=array=] 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 array.
          </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 [=object=]
          |json:JSON|, |manifest:ordered map|, and |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 the type of |json|["shortcuts"] is not [=array=], return.
          </li>
          <li>[=list/For each=] |entry:object| of |json|["shortcuts"]:
            <ol>
              <li>Let |shortcut:Ordered map| be [=process a shortcut=] with
              |entry|.
              </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>
        <h3>
          `protocol_handlers` member
        </h3>
        <p>
          The [=manifest's=] <code><dfn  data-dfn-for="manifest">protocol_handlers</dfn></code> member is an <a>array</a>
          of <a>protocol handler description</a>s that allows a web application to
          handle URL protocols.
        </p>
        <p class="example">
          Protocol handlers could, for instance, be used for web app
          communication where one app directly invokes another and passes data
          via custom protocol links.
        </p>
        <p>
          How protocol handlers are presented, and how many of them are shown
          to the user, is at the discretion of the user agent and/or operating
          system.
        </p>
        <p>To <dfn>process the `protocol_handlers` member</dfn>, given [=object=] |json:JSON|, |manifest:ordered map|, and |manifest URL:URL|:</p>
        <ol>
          <li>Let <var>processedProtocolHandlers</var> be a new [=list=].
          </li>
          <li>[=list/For each=] <var>protocol_handler</var> (<a>protocol handler description</a>):
            <ol>
              <li>If |protocol_handler|["protocol"] or
              <var>protocol_handler</var>["url"] is undefined, [=iteration/continue=].
              </li>
              <li>Set <var>protocol_handler</var>["url"] to the result of [=URL
              Parser|parsing=] <var>protocol_handler</var>["url"] using
              <var>manifest URL</var> as the base URL. If the result is 
              failure, [=iteration/continue=].
              </li>
              <li>If <var>protocol_handler</var>["url"] is not
              [=manifest/within scope=] of <var>manifest URL</var>, [=iteration/continue=].
              </li>
              <li>If <var>protocol_handler</var>["url"] already exists in <var>
                processedProtocolHandlers</var>, [=iteration/continue=].
              </li>
              <li>
                [=List/Append=] |protocol_handler| to
                <var>processedProtocolHandlers</var>.
              </li>
            </ol>
          </li>
          <li>
           [=list/For each=]  |processedProtocolHandlers|, [=register a protocol handler=].
         </li>
      </ol>
        <p>
          A user agent SHOULD ask users for permission before registering a
          <a>protocol handler description</a> <var>protocol_handler</var>s as the
          default handler for a protocol with the host operating system. A user
          agent MAY truncate the list of <a>protocol handler description</a>
          <var>protocol_handlers</var> presented in order to remain consistent
          with the conventions or limitations of the host operating system.
        </p>
        <aside class="example">
          <p>
            In the following example, the developer has included two
            <a>protocol handler description</a> <var>protocol_handler</var>s. Assuming
            the the manifest's URL is
            <samp>https://example.com/manifest.webmanifest</samp>:
          </p>
          <ul>
            <li>The first protocol handler would register to handle "web+music"
            URLs (e.g.: web+music://#1234). When activated, the user agent
            would instantiate a new <a>top-level browsing context</a> and
            navigate to
            <samp>https://example.com/play?songId=web+music://%231234</samp>.
            </li>
            <li>The second protocol handler would be ignored, as the protocol
            provided does not start with "web+" and is not part of the
            [=safelist=].
            </li>
          </ul>
          <pre class="example json">
            {
              "protocol_handlers": [
                {
                  "protocol": "web+music",
                  "url": "/play?songId=%s"
                },
                {
                  "protocol": "store",
                  "url": "/buy?songId=%s"
                }
              ]
            }
          </pre>
        </aside>
      </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>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 <a>extension point</a> 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 [^link^] |el:HTMLLinkElement| and a
            [=Response=] |response|.
          </p>
          <ol class="algorithm">
            <li>Let |document URL:URL| be |el|'s [=Node/node document=]'s
            [=Document/URL=].
            </li>
            <li>Assert: |document URL:URL| is not null.
            </li>
            <li>Let |json| be the result of [=parse JSON from bytes=]
            |response|'s [=response/body=].
            </li>
            <li>If the |json| is a parsing exception, or the type of |json| is
            not [=object=]:
              <ol>
                <li>Set |json:object| to an empty [=object=] (i.e., equivalent
                of JSON parsing the string `"{}"`).
                </li>
              </ol>
            </li>
            <li>Let |manifest| be a new [=ordered map=] «[ "display" →
            "browser", "dir" → "auto", "start_url" → |document URL| ]».
            </li>
            <li>[=Process the `dir` member=] passing |json| and |manifest|.
            </li>
            <li>[=Process the `lang` member=] passing |json| and |manifest|.
            </li>
            <li>[=list/For each=] |member:string| of [=list=] « "name",
            "short_name" »:
              <ol>
                <li>[=Process a text member=] passing |json|, |manifest|, and
                |member|.
                </li>
              </ol>
            </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 `scope` member=] passing |json|, |manifest|, and
            |manifest URL|.
            </li>
            <li>[=list/For each=] |member:string| of [=list=] « "theme_color",
            "background_color" »:
              <ol>
                <li>[=Process a color member=] passing |json|, |manifest|, and
                |member|.
                </li>
              </ol>
            </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 `protocol_handlers` member=] passing |json|,
              |manifest|, and |manifest URL|.
              </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>
              <a>Extension point</a>: process any proprietary and/or other
              supported members at this point in the algorithm.
            </li>
            <li>Let [=document=]'s <dfn 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 JSON |json:JSON|,
            [=ordered map=] |map:ordered map|, and [=string=] |member:string|:
          </p>
          <ol class="algorithm">
            <li>If the type of |json|[member] is not [=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 [=object=] |json:JSON|,
            [=ordered map=] |map:ordered map|, and [=string=] |member:string|:
          </p>
          <ol class="algorithm">
            <li>If the type of |json|[|member|] is not [=string=], return.
            </li>
            <li>Set |map|[member] to the value of |json|[|member|].
            </li>
          </ol>
        </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>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>
          <aside class="issue" data-number="446"></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 "<a>monochrome</a>" 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 [=any|any purpose=].
        </p>
        <p>
          The <dfn>icon purposes</dfn> are as follows:
        </p>
        <dl>
          <dt>
            "<dfn>monochrome</dfn>"
          </dt>
          <dd>
            <aside class="issue atrisk" data-number="905"></aside>
          </dd>
          <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>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>any</dfn>" (default)
          </dt>
          <dd>
            The user agent is free to display the icon in any context.
          </dd>
        </dl>
        <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 [=object=]
          |json:image|:
        </p>
        <ol class="algorithm">
          <li>If the type of |json|["purpose"] is not [=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 |keyword| is not one of the [=icon purposes=], 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 <a>maskable</a> 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 <a>maskable</a> 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 <a>maskable</a> 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
          <a>monochrome</a> 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 <a>monochrome</a> 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 <a>monochrome</a> 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 [=array=]
          |images:array|, [=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 the type of |images| is not [=array=], 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
        [=object=] 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>
      </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 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 following steps:
        </p>
        <ol class="algorithm">
          <li>Let <var>url</var> be <var>shortcut.url</var>.
          </li>
          <li>Let <var>browsing context</var> be the result of creating a new
          <a>top-level browsing context</a>.
          </li>
          <li>
            <a>Navigate</a> <var>browsing context</var> to <var>url</var>.
          </li>
        </ol>
      </section>
      <section>
        <h2>
          Processing shortcut items
        </h2>
        <p>
          To <dfn>process a shortcut</dfn>, given [=object=] |item:object|:
        </p>
        <ol class="algorithm">
          <li>If the type of |item| is not [=object=], return failure.
          </li>
          <li>If |item|["name"] is missing or |item|["name"] is the empty
          string, return failure.
          </li>
          <li>If the type of |item|["url"] is not [=string=], return failure.
          </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 |manifest URL|,
          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>
        ProtocolHandler items
      </h2>
      <p>
        Each <dfn>protocol handler description</dfn> is an [=object=] that 
        represents a protocol that the web application wants to handle. It has
        the following members:
      </p>
      <ul>
        <li>[=`protocol`=]
        </li>
        <li>[=`url`=]
        </li>
      </ul>
      <p>
        A user agent SHOULD use these values to register the web application as
        a handler with the operating system. When the user activates a protocol
        handler URL, the user agent SHOULD run <a>handling a protocol
        launch</a>.
      </p>
      <p class="note">
        [[HTML]]'s {{NavigatorContentUtils/registerProtocolHandler()}} allows web sites
        to register themselves as possible handlers for particular protocols.
        What constitutes valid <code>protocol</code> and <code>url</code>
        values for <a>protocol handler description</a>s is defined in that API. Also
        note that the [[HTML]] API uses [=url/scheme=]
        where we use <code>protocol</code> but the same restrictions apply.
      </p>
      <section>
        <h3>
          `protocol` member
        </h3>
        <p>
          The <dfn>protocol</dfn> member of a <a>protocol handler description</a> is a
          <a>string</a> that represents the protocol to be handled, such as
          `mailto` or `web+auth`.
        </p>
        <p>
          The <a>protocol</a> member of a <a>protocol handler description</a> is
          equivalent to {{NavigatorContentUtils/registerProtocolHandler()}}'s
          |scheme| argument defined in [[HTML]].
        </p>
      </section>
      <section>
        <h3>
          `url` member
        </h3>
        <p>
          The <dfn>url</dfn> member of a <a>protocol handler description</a> is the
          <a>URL</a> [=manifest/within scope=] of the application that opens
          when the associated protocol is activated.
        </p>
        <p>
          The <a>url</a> member of a <a>protocol handler description</a> is equivalent
          to {{NavigatorContentUtils/registerProtocolHandler()}}'s
          <code>url</code> argument defined in [[HTML]].
        </p>
      </section>
      <section>
        <h3>
          <dfn>Handling a protocol launch</dfn>
        </h3>
        <p>
          When a <a>protocol handler description</a> <var>protocol_handler</var> having
          [=manifest=] <var>manifest</var> is invoked, it goes through the same
          steps used to [=invoke a protocol handler=] defined in [=HTML=],
          where the user agent SHOULD navigate to [=url=] and the appropriate
          browsing context is set to a new top level browsing context.
        </p>
      </section>
      <section>
        <h3>
          Privacy and Security considerations
        </h3>
        <p>
          Privacy concerns for custom scheme handling are detailed in the
          Security and privacy section of
          {{NavigatorContentUtils/registerProtocolHandler()}}.
        </p>
        <p>
          The user agent MUST ask for permission when using a protocol
          handler for the first time. This feature requires user interaction
          and a script cannot communicate with another application on its
          own.
        </p>
      </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 array 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>
        For example, on user agents that support installation, a web
        application could be presented and launched in a way that, to the
        end-user, is indistinguishable from native applications: such as
        appearing as a labeled icon on the home screen, launcher, or start
        menu. When launched, the manifest is <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 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 [=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>
        Display modes
      </h2>
      <p>
        A <dfn>display mode</dfn> represents how the web application is being
        presented within the context of an OS (e.g., in fullscreen, etc.).
        Display modes correspond to user interface (UI) metaphors and
        functionality in use on a given platform. The UI conventions of the
        display modes are purely advisory and implementers are free to
        interpret them how they best see fit.
      </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
        <a>browser</a> <a>display mode</a> as the <a>default display mode</a>.
        As such, the user agent MUST support the <a>browser</a> <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>[=browser=] is «».
        </li>
        <li>[=minimal-ui=] is « "[=browser=]" ».
        </li>
        <li>[=standalone=] is « "[=minimal-ui=]", "[=browser=]" ».
        </li>
        <li>[=fullscreen=] is « "[=standalone=]", "[=minimal-ui=]",
        "[=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>
          <a>Extension point</a>: 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 {{browser}} is in every mode's [=fallback chain=],
        and the requirement that all user agents support the {{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 values</dfn> are:
      </p>
      <dl>
        <dt>
          "<dfn>fullscreen</dfn>"
        </dt>
        <dd>
          Opens the web application with browser UI elements hidden and takes
          up the entirety of the available display area.
        </dd>
        <dt>
          "<dfn>standalone</dfn>"
        </dt>
        <dd>
          Opens the web application to look and feel like a standalone native
          application. This can include the application having a different
          window, its own icon in the application launcher, etc. In this mode,
          the user agent will exclude standard browser UI elements such as an
          URL bar, but can include other system UI elements such as a status
          bar and/or system back button.
        </dd>
        <dt>
          "<dfn>minimal-ui</dfn>"
        </dt>
        <dd>
          This mode is similar to <a>standalone</a>, but provides the end-user
          with some means to access a minimal set of UI elements for
          controlling navigation (i.e., back, forward, reload, and perhaps some
          way of viewing the document's address). A user agent can include
          other platform specific UI elements, such as "share" and "print"
          buttons or whatever is customary on the platform and user agent.
        </dd>
        <dt>
          "<dfn>browser</dfn>" (default)
        </dt>
        <dd>
          Opens the web application using the platform-specific convention for
          opening hyperlinks in the user agent (e.g., in a browser tab or a new
          window).
        </dd>
      </dl>
      <p class="note">
        The <a>fullscreen</a> <a>display mode</a> is orthogonal to, and works
        independently of, the [[[FULLSCREEN]]]. The <a>fullscreen</a>
        <a>display mode</a> affects the fullscreen state of the browser window,
        while the [[FULLSCREEN]] API operates on an element contained within
        the viewport. As such, a web application can have its <a>display
        mode</a> set to <a>fullscreen</a>, while `document.fullScreenElement`
        returns `null`, and `fullscreenEnabled` returns `false`.
      </p>
      <section data-cite="css-conditional-3">
        <h3>
          The `'display-mode'` media feature
        </h3>
        <table class="def descdef mq">
          <tbody>
            <tr>
              <th>
                Name:
              </th>
              <td>
                <dfn data-dfn-for="@media" data-dfn-type="descriptor"
                data-export="">display-mode</dfn>
              </td>
            </tr>
            <tr>
              <th>
                For:
              </th>
              <td>
                <a data-xref-type="css-at-rule">@media</a>
              </td>
            </tr>
            <tr>
              <th>
                Value:
              </th>
              <td class="prod">
                <a>fullscreen</a> | <a>standalone</a> | <a>minimal-ui</a> |
                <a>browser</a>
              </td>
            </tr>
            <tr>
              <th>
                Type:
              </th>
              <td>
                discrete
              </td>
            </tr>
          </tbody>
        </table>
        <p>
          The `display-mode` media feature represents, via a CSS media query
          [[MEDIAQ]], the <a>display mode</a> of the web application. This
          media feature applies to the top-level browsing context and any child
          browsing contexts. Child browsing contexts reflect the <a>display
          mode</a> of the <a>top-level browsing context</a>.
        </p>
        <p>
          A user agent MUST expose the '`display-mode`' media feature
          irrespective of whether a manifest is being applied to a browsing
          context. For example, if the end-user puts the whole user agent into
          fullscreen, then the user agent would reflect this change to CSS and
          scripts via the '`display-mode`' media feature.
        </p>
        <aside class="note">
          <p>
            Please note that the `fullscreen` <a>display mode</a> is not
            directly related to the CSS `:fullscreen` pseudo-class specified in
            the [[[FULLSCREEN]]]. The `:fullscreen` pseudo-class matches
            exclusively when a [[HTML]] element is put into the fullscreen
            element stack. However, a side effect of calling the
            `requestFullscreen()` method on an element using the [[FULLSCREEN]]
            API is that the browser window can enter a fullscreen mode at the
            OS-level. In such a case, both `:fullscreen` and `(display-mode:
            fullscreen)` will match.
          </p>
          <p>
            On some platforms, it is possible for a user to put a browser
            window into fullscreen without the aid of the [[[FULLSCREEN]]].
            When this happens, the `:fullscreen` pseudo class will not match,
            but `(display-mode: fullscreen)` will match. This is exemplified in
            CSS code below.
          </p>
          <pre class="example css">
            /* applies when the window is fullscreen */
            @media all and (display-mode: fullscreen) {
                ...
            }

            /* applies when an element goes fullscreen */
            #game:fullscreen {
                ...
            }
          </pre>
        </aside>
        <p>
          A user agent MUST reflect the applied <a>display mode</a> of the web
          application via a CSS media query [[MEDIAQ]].
        </p>
        <section>
          <h4>
            Examples
          </h4>
          <p>
            An example in CSS:
          </p>
          <pre class="example css" title="Using 'display-mode' media feature">
            @media all and (display-mode: minimal-ui) {
              /* ... */
            }
            @media all and (display-mode: standalone) {
              /* ... */
            }
          </pre>
          <p>
            Accessing the display-mode media feature in ECMAScript through
            `matchMedia()` of [[CSSOM-VIEW]]:
          </p>
          <pre class="example js" title=
          "Accessing 'display-mode' media feature with script">
            const standalone = matchMedia( '(display-mode: standalone)' );

            standalone.onchange = (e) =&gt; {
              /* handle changes to display mode */
            }

            if (standalone.matches) {
              /* do standalone things */
            }
          </pre>
        </section>
      </section>
    </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 "<a>browser</a>", 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-mode'` media feature allows an origin access to aspects
        of a user’s local computing environment and, together with the
        `display` member, allows an origin some measure of control over a user
        agent’s native UI: Through a CSS media query, a script can know the
        display mode of a web application. An attacker could, in such a case,
        exploit the fact that an application is being displayed in fullscreen
        to mimic the user interface of another application.
      </p>
    </section>
    <section>
      <h2>
        IANA considerations
      </h2>
      <p>
        The following registrations are for community review and will be
        submitted to the <a href="https://www.ietf.org/iesg/">IESG</a> for
        review, approval, and registration with <a href=
        "https://www.iana.org/">IANA</a>.
      </p>
      <section>
        <h3>
          Media type registration
        </h3>
        <p>
          This section contains the required text for MIME media type
          registration with <a href="https://www.iana.org/">IANA</a>.
        </p>
        <p>
          The <dfn data-export="">application manifest MIME type</dfn> is
          <dfn data-export="">`application/manifest+json`</dfn>.
        </p>
        <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 MIME 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
          </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>
        <p class="note">
          A request to register the `manifest` link relation type been
          submitted to IANA.
        </p>
        <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 manifest is
            [=fetched=].
          </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 <a>extension point</a> 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. As such, the RECOMMENDED way to add a new
            proprietary manifest member as an extension is to use a vendor
            prefix.
          </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 vendor
            extensions.
          </p>
          <pre class="example json" title="Vendor extensions">
            {
              ...
              "webkit_fancy_feature": "some/url/img",
              "moz_awesome_thing": { ... },
              "vendor_example_site_verification": "KEY_9864D0966935"
              ...
            }
          </pre>
        </section>
      </section>
    </section>
    <section class="appendix informative">
      <h2>
        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/beforeinstallprompt">`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>