2.1 AppBannerPromptOutcome enum

enum AppBannerPromptOutcome {
    "accepted",
    "dismissed"
};

The AppBannerPromptOutcome enum's values represent the outcomes from presenting the end-user with an install prompt.

accepted:

The end-user indicated that they would like the user agent to install the web application.

dismissed:

The end-user dismissed the install prompt.

2.2 Authority of the manifest's metadata

When a manifest is linked from a Document, it indicates to the user agent that the metadata is authoritative: that is, the user agent SHOULD use the metadata of the manifest instead of the one in the Document. However, in cases where metadata is missing, or in error, a user agent MAY fallback to the Document to find suitable replacements for missing manifest members (e.g., using application-name in place of short_name).

2.3 Application's name

The application's name is derived from either the name member or short_name member (if either is present) - otherwise, it is generated by the user agent or provided by the end-user.

When either member is missing from the manifest, a user agent MAY use the name member as a fallback for the short_name member or vice versa.

If the name and short_name members are undefined, the user agent SHOULD assign a default name (e.g., "Untitled"). Alternatively, a user agent MAY allow the end-user to input some text that can serve as the application's name.

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

2.4 Installation process

An installation process is an attempt by the user agent to install a web application. The details of such a process (i.e., the display of an install UI, and any resulting IO operations of the host OS) are left up to implementers. Implementers need to be aware that there are privacy and security considerations that directly relate to the installation process.

For the purpose of this specification, the installation succeeded once the installation process succeeds in installing the web application (e.g., an icon was successfully placed onto the device's homescreen). If the end-user cancels the installation process (even if they manually triggered it, and then changed their minds), then the installation was canceled. Otherwise, the installation failed. Reasons for installation failure can include, for example, the OS denying permission to the user agent to add an icon to the homescreen of the device and the end-user rejecting the installation.

The steps to install the web application are given by the following algorithm:

1. Let window be the Window object of the top-level browsing context for which the user agent will attempt installation.
2. Then, in parallel:
   1. Instantiate an installation process.
   2. Let manifest and manifest URL be the result of obtaining the manifest.
   3. If obtaining the manifest results in an error, a user agent can, at this point, fall back to using the top-level browsing context Document's metadata to populate an installation process's UI.
   4. If obtaining the manifest succeeds, and the result of running the steps for processing the serviceworker member with manifest returns a valid registration, a user agent can at this point
      1. Let client be the top-level browsing context Document's relevant settings object, or null if unavailable.
      2. Invoke Start Register with scope and src members of the registration, a new promise, client, manifest URL, plus the type and use_cache members of the registration,
      in which case the state of the settled promise determines whether the installation succeeded or not.
   5. If the installation succeeded, queue a task on the application life-cycle task source to fire an event named appinstalled at the window object.

2.5 Install prompts

There are multiple ways that the installation process can be triggered:

• An end-user can manually trigger the installation process through the user agent's UI.
• The installation process can occur through an automated install prompt: that is, a UI that the user agent presents to the user when, for instance, there are sufficient installability signals to warrant installation of the web application.
• The installation process can occur through a site-triggered install prompt: the site can programmatically request that the user agent present an install prompt to the user. The user agent MAY restrict the availability of this feature to cases where, for instance, there are sufficient installability signals to warrant installation of the web application.

Prior to presenting an automated install prompt, a user agent MUST run the steps to notify that an install prompt is available, to give the site the opportunity to prevent the default action (which is to install the application). Alternatively, the user agent MAY run the steps to notify that an install prompt is available at any time, giving the site the opportunity to show a site-triggered install prompt without automatically showing the prompt.

In either case, when a user agent presents an install prompt, the end-user's choice is represented either "accepted" or "dismissed". These values are represented in the API of this specification via the AppBannerPromptOutcome enum.

The steps to notify that an install prompt is available are given by the following algorithm:

1. Wait until the Document of the top-level browsing context is completely loaded.
2. If there is already an installation process being presented, terminate this algorithm.
3. Queue a task on the application life-cycle task source to do the following:
   1. Let event be a newly constructed BeforeInstallPromptEvent named beforeinstallprompt, with its cancelable attribute initialized to true.
   2. Let mayShowPrompt be the result of firing event at the Window object of the top-level browsing context.
   3. If mayShowPrompt is true, then the user agent MAY, in parallel, request to present an install prompt with event.

2.6 Privacy and security considerations

During the installation process, it is RECOMMENDED that the user agent allow the end-user to inspect the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.

It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.

3.1 BeforeInstallPromptEvent Interface

[Constructor]
interface BeforeInstallPromptEvent : Event {
    Promise<PromptResponseObject> prompt();
};

dictionary PromptResponseObject {
    AppBannerPromptOutcome userChoice;
};

The BeforeInstallPromptEvent is dispatched when the site is allowed to present a site-triggered install prompt, or prior to the user agent presenting an automated install prompt. It allows the site to cancel the automated install prompt, as well as manually present the site-triggered install prompt.

The PromptResponseObject contains the result of calling prompt(). It contains one member, userChoice, which states the user's chosen outcome.

An instance of a BeforeInstallPromptEvent has the following internal slots:

[[didPrompt]]

A boolean, initially false. Represents whether this event was used to present an install prompt to the end-user.

[[userResponsePromise]]

A promise that represents the outcome of presenting an install prompt.

window.addEventListener("beforeinstallprompt", event => {
  // Suppress automatic prompting.
  event.preventDefault();

  // Show the (disabled-by-default) install button. This button
  // resolves the installButtonClicked promise when clicked.
  installButton.disabled = false;

  // Wait for the user to click the button.
  installButton.addEventListener("click", async e => {
    // The prompt() method can only be used once.
    installButton.disabled = true;

    // Show the prompt.
    const { userChoice } = await event.prompt();
    console.info(`user choice was: ${userChoice}`);
  });
});

3.2 Extensions to the Window object

The following extensions to the Window object specify the event handler attributes on which events relating to the installation of a web application are fired.

partial interface Window {
    attribute EventHandler onappinstalled;
    attribute EventHandler onbeforeinstallprompt;
};

function handleInstalled(ev) {
  const date = new Date(ev.timeStamp / 1000);
  console.log(`Yay! Our app got installed at ${date.toTimeString()}.`);
}

// Using the event handler IDL attribute
window.onappinstalled = handleInstalled;

// Using .addEventListener()
window.addEventListener("appinstalled", handleInstalled);
          

4.1 Security considerations

When the navigation scope is unbounded and a display mode other than browser is being applied, it is RECOMMENDED that user agents signal to the end-user when security and/or privacy sensitive navigations occur. The manner of signaling is left up to implementers, but can include things like showing the URL of the application context, dropping out of fullscreen to the browser display mode. Examples of security and/or privacy sensitive navigations include, but are not limited to:

• the application context being navigated from a secure connection to an insecure connection (or vice versa).
• the application context being navigated to a different origin.

This specification distinguishes between behavior in first-party and third-party contexts. In particular, if a scope member is declared in the manifest, it is not possible to navigate the top-level browsing context to somewhere outside the scope while the manifest is applied to the top-level browsing context. That's not to say that the web application cannot be navigated: just that the set of URLs to which the manifest applies is restricted by the navigation scope.

4.2 Deep links

A deep link is a URL that is within scope of an installed web application.

An application context can be instantiated through a deep link (a URL that is within scope of the installed web application); in which case, the manifest is applied and the deep link is loaded within the context of a web application.

5.1 Privacy and security considerations

When the fullscreen display mode is applied, it is RECOMMENDED that the user agent provides the end-user a means to consult common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.

Additionally, when applying a manifest that sets the display mode to anything except "browser", it is RECOMMENDED that the user agent clearly indicate to the end-user that their are leaving the normal browsing context of a web browser. Ideally, launching or switching to a web application is performed in a manner that is consistent with launching or switching to other applications in the host platform. For example, a long and obvious animated transition, or speaking the text "Launching application X".

5.2 The 'display-mode' media feature

The display-mode media feature represents, via a CSS media query [MEDIAQ], the display mode of the web application. This media feature applies to the top-level browsing context and any child browsing contexts. Child browsing contexts reflect the display mode of the top-level browsing context.

A user agent MUST expose the 'display-mode' media feature irrespective of whether a manifest is being applied to a browsing context. For example, if the end-user puts the whole user agent into fullscreen, then the user agent would reflect this change to CSS and scripts via the 'display-mode' media feature.

/* applies when the window is fullscreen */
@media all and (display-mode: fullscreen) {
    ...
}

/* applies when an element goes fullscreen */
#game:fullscreen {
    ...
}

Value:

fullscreen | standalone | minimal-ui | browser

Applies to:

visual media types

Accepts min/max prefixes:

No

A user agent MUST reflect the applied display mode of the web application via a CSS media query [MEDIAQ].

@media all and (display-mode: minimal-ui) {
  /* ... */
}
@media all and (display-mode: standalone) {
  /* ... */
}

const standalone = matchMedia( '(display-mode: standalone)' );

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

if (standalone.matches) {
  /* do standalone things */
}

6.1 Linking to a manifest

The manifest keyword can be used with a [HTML] link element. This keyword creates an external resource link.

The media type for a manifest serves as the default media type for resources associated with the manifest link type.

To obtain a manifest, the user agent MUST run the steps for obtaining a manifest. The appropriate time to obtain the manifest is left up to implementations. A user agent MAY opt to delay fetching a manifest until after the document and its other resources have been fully loaded (i.e., to not delay the availability of content and scripts required by the document).

A manifest is obtained and applied regardless of the media attribute of the link element matches the environment or not.

7.1 Obtaining a manifest

The steps for obtaining a manifest are given by the following algorithm. The algorithm, if successful, returns a processed manifest and the manifest URL; otherwise, it terminates prematurely and returns nothing. In the case of nothing being returned, the user agent MUST ignore the manifest declaration. In running these steps, a user agent MUST NOT delay the load event.

1. From the Document of the top-level browsing context, let manifest link be the first link element in tree order whose rel attribute contains the token manifest.
2. If manifest link is null, terminate this algorithm.
3. If manifest link's href attribute's value is the empty string, then abort these steps.
4. Let manifest URL be the result of parsing the value of the href attribute, relative to the element's base URL. If parsing fails, then abort these steps.
5. Let request be a new [FETCH] request, whose URL is manifest URL, and whose context is " manifest".
6. If the manifest link's crossOrigin attribute's value is 'use-credentials', then set request's credentials to 'include'.
7. Await the result of performing a fetch with request, letting response be the result.
8. If response is a network error, terminate this algorithm.
9. Let text be the result of UTF-8 decoding response's body.
10. Let manifest be the result of running the steps for processing a manifest with text, manifest URL, and the URL that represents the address of the top-level browsing context.
11. Return manifest and manifest URL.

HTTP/1.1 200 OK
Cache-Control: max-age=2592000
Content-Type: application/manifest+json

{
  "lang": "en",
  "name": "Resist",
  "start_url": "/start.html",
  "display": "fullscreen",
  "orientation": "landscape"
}

7.1.1 Content security policy

A user agent MUST support [CSP3].

The manifest-src and default-src directives govern the origins from which a user agent can fetch a manifest. As with other directives, by default the manifest-src directive is *, meaning that a user agent can, [ FETCH]'s CORS permitting, fetch the manifest cross-domain. Remote origins (e.g., a CDN) wanting to host manifests for various web applications will need to include the appropriate CORS response header in their HTTP response (e.g., Access-Control-Allow-Origin: https://example.com).

7.2 Processing the manifest

When instructed to issue a developer warning, the user agent MAY report the conformance violation to the developer in a user-agent-specific manner (e.g., report the problem in an error console), or MAY ignore the error and do nothing.

When instructed to ignore, the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.

The following algorithm provides an extension point: other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm.

The steps for processing a manifest are given by the following algorithm. The algorithm takes a text string as an argument, which represents a manifest, and a URL manifest URL, which represents the location of the manifest, and a URL document URL. The output from inputting an JSON document into this algorithm is a processed manifest .

1. Let parsed manifest be an empty object.
2. Let manifest be the result of parsing text. If parsing throws an error:
   1. Issue a developer warning with any details pertaining to the JSON parsing error.
   2. Set manifest to be the result of parsing the string "{}".
3. If Type(manifest) is not "object":
   1. Issue a developer warning that the manifest needs to be an object.
   2. Set manifest to be the result of parsing the string "{}".
4. Extension point: process any proprietary and/or other supported members at this point in the algorithm.
5. Let the default direction of parsed manifest be the result of running the steps for processing the dir member with manifest as the argument.
6. Let start URL of parsed manifest be the result of running the steps for processing the start_url member with manifest, manifest URL, and document URL as arguments.
7. Let service worker registration of parsed manifest be the result of running the steps for processing the serviceworker member with manifest, manifest URL, and serviceworker as arguments.
8. Let display mode of parsed manifest be the result of running the steps for processing the display member with manifest as the argument.
9. Let orientation of parsed manifest be the result of running the steps for processing the orientation member with manifest and display mode as arguments.
10. Let name of parsed manifest be the result of running the steps for processing the name member with manifest as the argument.
11. Let description of parsed manifest be the result of running the steps for processing the description member with manifest as the argument.
12. Let language of parsed manifest be the result of running the steps for processing the lang member with manifest as the argument.
13. Let short name of parsed manifest be the result of running the steps for processing the short_name member with manifest as the argument.
14. Let icons of parsed manifest be the result of running the steps for processing an array of images with manifest, manifest URL, and "icons" as arguments.
15. Let scope of parsed manifest be the result of running the steps for processing the scope member with manifest, manifest URL, document URL, start URL as arguments.
16. Let related applications of parsed manifest be the result of running the steps for processing the related_applications member with manifest as argument.
17. Let prefer related applications of parsed manifest be the result of running the steps for processing the prefer_related_applications member with manifest as argument.
18. Let theme color of parsed manifest be the result of running the steps for processing the theme_color member with manifest as argument.
19. Let background_color of parsed manifest be the result of running the steps for processing the background_color member with manifest as argument.
20. Let iarc_rating_id of parsed manifest be the result of running the steps for processing the iarc_rating_id member with manifest as argument.
21. Let screenshots of parsed manifest be the result of running the steps for processing an array of images with manifest, manifest URL, and "screenshots" as arguments.
22. Return parsed manifest.

7.3 Applying the manifest

A manifest is applied to a top-level browsing context, meaning that the members of the manifest are affecting the presentation or behavior of a browsing context.

A top-level browsing context that has a manifest applied to it is referred to as an application context.

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent MUST immediately navigate to the deep link with replacement enabled. Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with replacement enabled.

The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.

7.4 Updating the manifest

8.1 dir member

The dir member specifies the base direction for the directionality-capable members of the manifest. The dir member's value can be set to one of the text-direction values.

The directionality-capable members are:

• description member.
• name member.
• short_name member.

The text-direction values are the following, implying that the value of the directionality-capable members is by default:

ltr

left-to-right text.

rtl

right-to-left text.

auto

programmatically determined from the value of the member.

When displaying the directionality-capable members to an end-user, the user agent MUST use the base direction to compute directional runs and layout or position text correctly in text containing mixed-direction sequences [BIDI]. When the base direction is "auto" the user agent MUST run the steps to programmatically determine the directionality of a member - and use the resulting text-direction value to assist in displaying the value of the member.

The steps to programmatically determine the directionality of a member are as follows. The algorithm takes the value of a member.

1. Find the first character (in logical order) of the value that is of bidirectional character type L, AL, or R [ BIDI].
2. If such a character is found and it is of bidirectional character type AL or R, return "rtl".
3. Otherwise, return "ltr".

The steps for processing the dir member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns one of the text-direction values.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "dir".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. If Type(value) is "undefined", return "auto".
3. Otherwise, Trim(value), convert to lower-case, and let direction be the result.
4. If direction not one one the text-direction values, then:
   1. Issue a developer warning that the value is invalid.
   2. Return "auto".
5. Return direction.

8.2 lang member

The lang member is a language tag (string) that specifies the primary language for the values of the manifest's directionality-capable members (as knowing the language can also help with directionality).

A language tag is a string that matches the production of a Language-Tag defined in the [BCP47] specifications (see the IANA Language Subtag Registry for an authoritative list of possible values). That is, a language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS ("-"). For example, the 'en-AU' language range represents English as spoken in Australia, and 'fr-CA' represents French as spoken in Canada. Language tags that meet the validity criteria of [RFC5646] section 2.2.9 that can be verified without reference to the IANA Language Subtag Registry are considered structurally valid.

The steps for processing the lang member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "lang".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and let tag be the result.
4. If calling IsStructurallyValidLanguageTag with tag as the argument returns false, then:
   1. Issue a developer warning that the value is invalid.
   2. Return undefined.
5. Otherwise, return the result of calling the CanonicalizeLanguageTag abstract operation, passing tag as the argument.

8.3 name member

The name member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon).

The steps for processing the name member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "name".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

8.4 short_name member

The short_name member is a string that represents a short version of the name of the web application. It is intended to be used where there is insufficient space to display the full name of the web application.

The steps for processing the short_name member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "short_name".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

8.5 description member

The description member allows the developer to describe the purpose of the web application.

The steps for processing the description member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "description".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

8.6 scope member

The scope member is a string that represents the navigation scope of this web application's application context.

The steps for processing the scope member is given by the following algorithm. The algorithm takes a manifest manifest, a URL manifest URL , a URL document URL, and a URL start URL . This algorithm returns a URL or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of the manifest with argument "scope".
2. Let type be Type(value).
3. If type is not "string" or value is the empty string, then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return undefined.
4. Let scope URL be a new URL using value as input and manifest URL as the base URL.
5. If scope URL is failure:
   • Issue a developer warning.
   • Return undefined.
6. If scope URL is not same origin as document URL:
   1. Issue a developer warning that the scope needs to be same-origin as Document of the application context.
   2. Return undefined.
7. If start URL is not within scope of scope URL:
   1. Issue a developer warning that the start URL is not within scope of the navigation scope.
   2. Return undefined.
8. Otherwise, return scope URL.

8.7 icons member

The icons member is an array of image objects that can serve as iconic representations of the web application in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.

If there are multiple equally appropriate icons in icons, a user agent MUST use the last one declared in order at the time that the user agent collected the list of icons. If the user agent tries to use an icon but that icon is determined, upon closer examination, to in fact be inappropriate (e.g. because its content type is unsupported), then the user agent MUST try the next-most-appropriate icon as determined by examining the image object's members.

{
  "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"
      }]
 }

8.8 display member

The display member is a string, whose value is one of display modes values. The item represents the developer's preferred display mode for the web application. When the member is missing or erroneous, the user agent MUST use the fallback display mode.

The steps for processing the display member are given by the following algorithm. The algorithm takes a manifest manifest as an argument, and returns a string.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest passing "display" as the argument.
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is unsupported.
   2. Return the fallback display mode's value.
3. Otherwise, Trim(value), convert to lower-case, and set value to be the result.
4. If value does not match one of the display modes values:
   1. Issue a developer warning that the value is unsupported.
   2. Return the fallback display mode's value.
5. Return value.

8.9 orientation member

The orientation member is a string that serves as the default orientation for all top-level browsing contexts of the web application. The possible values are those of the OrientationLockType enum defined in [ SCREEN-ORIENTATION].

If the user agent honors the value of the orientation member as the default orientation, then that serves as the default orientation for the life of the web application (unless overridden by some other means at runtime). This means that the user agent MUST return the orientation to the default orientation any time the orientation is unlocked [ SCREEN-ORIENTATION] or the top-level browsing context is navigated.

Although the specification relies on the [SCREEN-ORIENTATION]'s OrientationLockType, it is OPTIONAL for a user agent to implement the [SCREEN-ORIENTATION] API. Supporting the [ SCREEN-ORIENTATION] API is, of course, RECOMMENDED.

Certain UI/UX concerns and/or platform conventions will mean that some screen orientations and display modes cannot be used together . Which orientations and display modes cannot be used together is left to the discretion of implementers. For example, for some user agents, it might not make sense to change the default orientation of an application while in browser display mode.

The steps for processing the orientation member are given by the following algorithm. The algorithm takes a manifest manifest and display mode display mode as an argument, and returns a string.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "orientation".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value), convert to lower-case, and set value to be the result.
4. If value is not one of the OrientationLockType enum values, or value is unsupported by the user agent, or the value cannot be used together with display mode:
   1. Issue a developer warning.
   2. Return undefined.
5. Return value.

8.10 start_url member

The start_url member is a string that represents the start URL , which is URL that the developer would prefer the user agent load when the user launches the web application (e.g., when the user clicks on the icon of the web application from a device's application menu or homescreen).

The start_url member is purely advisory, and a user agent MAY ignore it or provide the end-user the choice not to make use of it. A user agent MAY also allow the end-user to modify the URL when, for instance, a bookmark for the web application is being created or any time thereafter.

The steps for processing the start_url member are given by the following algorithm. The algorithm takes a manifest manifest, a URL manifest URL , and a URL document URL. This algorithm returns a URL.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of the manifest with argument "start_url".
2. Let type be Type(value).
3. If type is not "string" or value is the empty string:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return a new URL whose input is document URL.
4. Let url be a new URL using value as input and manifest URL as the base URL.
5. If url is failure:
   • Issue a developer warning.
   • Return a new URL whose input is document URL.
6. If url is not same origin as document URL:
   1. Issue a developer warning that the start_url needs to be same-origin as Document of the top-level browsing context.
   2. Return a new URL whose input is document URL.
7. Otherwise, return url.

8.11 serviceworker member

The serviceworker member describes a service worker as defined in [SERVICE-WORKERS-1].

The serviceworker member represents an intented service worker registration in form of a registration object

The steps for processing the serviceworker member are given by the following algorithm. The algorithm takes a manifest manifest. This algorithm returns a registration object registration, which can be undefined.

1. Let unprocessed registration be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "serviceworker".
2. Let src be the result of running the steps for processing the src member of a service worker with unprocessed registration and manifest URL.
3. If src is undefined, or if the result of running is origin potentially trustworthy with the origin of src is Not Trusted, issue a developer warning, abort these steps and return undefined.
4. Otherwise, let registration be an object with properties src, scope, type and use_cache. All properties initially set to undefined.
5. Set registration's src property to be src.
6. Let scope be the result of running the steps for processing the scope member of a service worker passing unprocessed registration.
7. If scope is undefined, issue a developer warning, abort these steps and return undefined.
8. Otherwise, set registration's scope property to be scope.
9. Let type be the result of running the steps for processing the type member of a service worker passing unprocessed registration.
10. If type is undefined, issue a developer warning, abort these steps and return undefined.
11. Otherwise, set registration's type property to be type.
12. Let use cache be the result of running the steps for processing the use_cache member of a service worker passing unprocessed registration.
13. If use cache is undefined, issue a developer warning, abort these steps and return undefined.
14. Otherwise, set registration's use_cache property to be use cache.
15. Return registration.

"serviceworker": {
  "src": "sw.js",
  "scope": "/foo",
  "use_cache": false
}

8.12 theme_color member

The theme_color member serves as the default theme color for an application context. What constitutes a theme color is defined in [HTML].

If the user agent honors the value of the theme_color member as the default theme color, then that color serves as the theme color for all browsing contexts to which the manifest is applied. However, a document may override the default theme color through the inclusion of a valid [HTML] meta element whose name attribute is "theme-color".

The steps for processing the theme_color member are given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "theme_color".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, let potential color be the result of running [CSS-SYNTAX-3]'s parse a component value algorithm with value as input. If parsing returns a syntax error, return undefined.
4. Let color be the result of attempting to parse potential color as a CSS color, as per [CSS-SYNTAX-3]. If parsing fails:
   1. Issue a developer warning.
   2. Return undefined.
5. Return color.

8.13 related_applications member

A related application is an application accessible to the underlying application platform that has a relationship with the web application associated with a manifest.

The related_applications member lists related applications and serves as an indication of such a relationship between web application and related applications. This relationship is unidirectional and unless a listed application claims the same relationship, the user agent MUST NOT assume a bi-directional endorsement.

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.

The steps for processing the related_applications member are given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a list of application objects applications, which can be empty.

1. Let applications be an empty list.
2. Let unprocessed applications be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "related_applications".
3. If unprocessed applications is an array, then:
   1. For each potential application in the array:
      1. Let platform be the result of running the steps for processing the platform member of an application with potential application.
      2. If platform is undefined, move onto the next item if any are left.
      3. Let id be the result of running the steps for processing the id member of an application with potential application.
      4. Let url be the result of running the steps for processing the url member of an application with potential application.
      5. If both id and url are undefined, move onto the next item if any are left.
      6. Let minVersion be the result of running the steps for processing the min_version member of an application with potential application.
      7. Let fingerprints be the result of running the steps for processing the fingerprints member of an application with potential application.
      8. Let application be an object with properties platform, id, url, min_version, and fingerprints respectively set to platform, id, url, minVersion, and fingerprints.
      9. Append application to applications.
4. Otherwise, if unprocessed applications is not undefined:
   1. Issue a developer warning that the type is not supported.
5. Return applications.

8.14 prefer_related_applications member

The prefer_related_applications member is a boolean value that is used as a hint for the user agent to say that related applications should be preferred over the web application. The user agent MUST consider the missing value as equivalent to have it set to false. If the prefer_related_applications 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 related applications instead.

The steps for processing the prefer_related_applications member are given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a boolean.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "prefer_related_applications".
2. If Type(value) is not "boolean":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return false.
3. Return value.

8.15 background_color member

The background_color member describes the expected background color of the web application. It repeats what is already available in the application stylesheet but can be used by the user agent to draw the background color of a web application for which the manifest is known before the files are actually available, whether they are fetched from the network or retrieved from disk.

The background_color member is only meant to improve the user experience while a web application is loading and MUST NOT be used by the user agent as the background color when the web application's stylesheet is available.

The steps for processing the background_color member are given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "background_color".
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, let potential color be the result of running [CSS-SYNTAX-3]'s parse a component value algorithm with value as input. If parsing returns a syntax error, return undefined.
4. Let color be the result of attempting to parse potential color as a CSS color, as per [CSS-SYNTAX-3]. If parsing fails:
   1. Issue a developer warning.
   2. Return undefined.
5. Return color.

8.16 screenshots member

The screenshots member is an array of image objects represent the web application in common usage scenarios.

9.1 Fetching image objects

To fetch an image object, the user agent MUST run the steps to fetch an image object. The algorithm takes an image object, the manifest URL, and the document (Document) from which the manifest was linked. It returns a Response:

1. Let request be a new Request.
2. Set the following properties of request:
   1. url is set to image object's URL.
   2. initiator is "manifest".
   3. type is "image".
   4. cors is "no-cors".
   5. referrer is manifest URL.
   6. client is document.
3. Perform a fetch using request and return the response.

9.2 Content security policy of image objects

The security policy that governs whether a user agent can fetch an icon image is governed by the img-src directive [ CSP3] associated with the manifest's owner Document.

HTTP/1.1 200 OK
Content-Type: text/html
Content-Security-Policy: img-src icons.example.com

<!doctype>
<html>
<link rel="manifest" href="manifest.webmanifest">

{
    "name": "custom manifest",
    "start_url": "https://boo",
    "icons": [{
        "src": "//icons.example.com/lowres"
      },
      {
        "src": "//other.com/hi-res"
      }]
}

9.3 purpose member

The purpose member is an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are the icon purposes.

When an image object is used as an icon, a developer can hint that the image is intended to serve some special purpose in the context of the host OS (i.e., for better integration).

For example, as a badge or "pinned" icon that is visually distinct, in color or form, from an application's launch icon. The user agent uses the value of the purpose member as a hint to determine where and how an image object is displayed. Unless declared otherwise by the developer, a user agent can use an icon for any purpose.

The icon purposes are as follows:

badge:

A user agent can present this icon where space constraints and/or color requirements differ from those of the application icon.

any:

The user agent is free to display the icon in any context.

The steps for processing a purpose member of an image are given by the following algorithm. The algorithm takes an image object image. This algorithm will return a set.

1. Let purpose be an empty set.
2. Let value be the result of calling the [[GetOwnProperty]] internal method of image passing " purpose" as the argument.
3. Let type be Type(value).
4. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Add "any" to purpose.
   3. Return purpose.
5. Let keywords be the result of splitting value on spaces.
6. For each keyword in keywords:
   1. Convert keyword to ASCII lowercase.
   2. If keyword is not one of the icon purposes, or is already contained in keywords, issue a developer warning and continue to the next keyword skipping the sub-steps below.
   3. Otherwise, add keyword to purpose.
7. if the size of purpose is 0, then add "any" to purpose.
8. Return purpose.

{
  "name": "News",
  "icons": [{
    "platform": "android",
    "purpose": "badge",
    "sizes": "16x16",
    "src": "icons/badges/android.png",
    "type": "image/png"
  }, {
    "purpose": "badge",
    "src": "icons/badges/safari.svg",
    "type": "image/svg"
  }],
}

9.4 sizes member

The sizes member of an image object is a string consisting of an unordered set of unique space-separated tokens which are ASCII case-insensitive that represents the dimensions of an image. Each keyword is either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The keywords represent icon sizes in raw pixels (as opposed to CSS pixels). When multiple image objects are available, a user agent MAY use the value to decide which icon is most suitable for a display context (and ignore any that are inappropriate).

The steps for processing a sizes member of an image are given by the following algorithm. The algorithm takes an image object image. This algorithm will return a set.

1. Let sizes be an empty set.
2. Let value be the result of calling the [[GetOwnProperty]] internal method of image passing " sizes" as the argument.
3. Let type be Type(value).
4. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return undefined.
5. Otherwise, parse value as if it was a [HTML] sizes attribute and let keywords be the result.
6. For each keyword in keywords:
   1. Convert keyword to ASCII lowercase and add the resulting string to sizes.
7. Return sizes.

9.5 src member

The src member of an image object is a URL from which a user agent can fetch the image's data.

The steps for processing the src member of an image are given by the following algorithm. The algorithm takes a image object icon, and a URL manifest URL , which is the URL from which the manifest was fetched. This algorithm will return a URL or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of image passing " src" as the argument.
2. Let type be Type(value).
3. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return undefined.
4. If Trim(value) is the empty string, then return undefined.
5. Otherwise, parse value using manifest URL as the base URL and return the result.

9.6 type member

The type member of an image object is a hint as to the media type of the image. The purpose of this member is to allow a user agent to ignore images of media types it does not support.

There is no default MIME type for image objects. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

The steps for processing the type member of an image are given by the following algorithm. The algorithm takes an image object as an argument, and returns either a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of potential image passing "type" as the argument.
2. Let type be Type(value).
3. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return undefined.
4. Trim(value) and set value to be resulting string.
5. If value is not a valid MIME type or the value of type is not a supported media format, issue a developer warning and return undefined.
6. Return value.

9.7 Processing an array of images

The steps for processing an array of images are given by the following algorithm. The algorithm takes a manifest, a URL manifest URL, which is the URL from which the manifest was fetched, and a string that represents the member name of the member which contains the array of image objects. This algorithm returns a list of image objects, which can be empty.

1. Let images be an empty list.
2. Let unprocessed images be the result of calling the [[GetOwnProperty]] internal method of manifest with member name as the argument.
3. If unprocessed images is an array, then:
   1. From unprocessed images, filter out any item where HasOwnProperty(item,"src") returns false.
   2. For each potential image in the array:
      1. Let src be the result of running the steps for processing the src member of an image with potential image and manifest URL.
      2. If src is undefined, move onto the next item in images (if any are left).
      3. Otherwise, let image be an object with properties src, type, and sizes. All properties initially set to undefined.
      4. Set image's src property to be src.
      5. Let type be the result of running the steps for processing the type member of an image passing potential image.
      6. If type is not undefined, set image's type property to be type.
      7. Let sizes be the list that result from running the steps for processing a sizes member of an image passing potential image.
      8. If sizes is not undefined, set image's sizes property to be sizes.
      9. Set image's purpose property to be the result of running the steps for processing a purpose member of an image passing potential image.
      10. Append image to images.
4. Otherwise, if unprocessed images is not undefined:
   1. Issue a developer warning that the type is not supported.
5. Return images.

11.1 platform member

The platform member represents the platform to which a containing object applies.

The following object types can make use of this member:

• Application object
• Image object

A platform represents a software distribution ecosystem or possibly an operating system.

The steps for processing the platform member of an application are given by the following algorithm. The algorithm takes an application object application. This algorithm will return a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of application passing "platform" as the argument.
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

12.1 src member

The service worker src member of a serviceworker object is a URL representing a service worker.

The steps for processing the src member of a service worker are given by the following algorithm. The algorithm takes a serviceworker object registration, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a URL or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of registration passing " src" as the argument.
2. Let type be Type(value).
3. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported.
   2. Return undefined.
4. If Trim(value) is the empty string, then return undefined.
5. Otherwise, parse value using manifest URL as the base URL and return the result.

12.2 scope member

The service worker scope member of a serviceworker object is the service worker's associated scope URL.

The steps for processing the scope member of a service worker are given by the following algorithm. The algorithm takes a serviceworker object registration, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a URL or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of registration passing "scope" as the argument.
2. Let type be Type(value).
3. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported and return undefined.
   2. Return null.
4. If Trim(value) is the empty string, then return undefined.
5. Otherwise, parse value using manifest URL as the base URL and return the result.

12.3 type member

The service worker type member of a serviceworker object is the service worker's worker type.

The steps for processing the type member of a service worker are given by the following algorithm. The algorithm takes a serviceworker object registration, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a string.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of registration passing " type" as the argument.
2. Let type be Type(value).
3. If type is not "string", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported and return undefined.
   2. Return "classic".
4. If Trim(value) is the empty string, then:
   1. Issue a developer warning that the type is unsupported.
   2. Return undefined.
5. Otherwise, Trim(value) and return the result.

12.4 use_cache member

The service worker use_cache member of a serviceworker object determines whether the user agent cache should be used when fetching the service worker.

The steps for processing the use_cache member of a service worker are given by the following algorithm. The algorithm takes a serviceworker object registration, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a boolean.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of registration passing " use_cache" as the argument.
2. Let type be Type(value).
3. If type is not "boolean", then:
   1. If type is not "undefined", issue a developer warning that the type is unsupported and return undefined.
   2. Otherwise, return false
4. Otherwise, return value.

13.1 url member

The url member of an application object represents the URL at which the application can be found.

The steps for processing the url member of an application are given by the following algorithm. The algorithm takes an application object application. This algorithm will return an URL or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of application passing "url" as the argument.
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Trim(value) and set value to be resulting string.
4. Otherwise, parse value and if the result is not failure, return the result, otherwise return undefined.

13.2 id member

The id member of an application object represents the id which is used to represent the application on the platform.

The steps for processing the id member of an application are given by the following algorithm. The algorithm takes an application object application. This algorithm will return a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of application passing "id" as the argument.
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

13.3 min_version member

The min_version member of an application object represents the minimum version of the application that is considered related to this web app. This version is a string with platform-specific syntax and semantics.

The steps for processing the min_version member of an application are given by the following algorithm. The algorithm takes an application object application. This algorithm will return a string or undefined.

1. Let value be the result of calling the [[GetOwnProperty]] internal method of application passing "min_version" as the argument.
2. If Type(value) is not "string":
   1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
   2. Return undefined.
3. Otherwise, Trim(value) and return the result.

13.4 fingerprints member

The fingerprints member of an application object represents a set of cryptographic fingerprints used for verifying the application. It is given as an array of fingerprint objects.

A fingerprint object has two properties: type and value. Each of these are strings, but their syntax and semantics are platform-defined.

The steps for processing the fingerprints member of an application are given by the following algorithm. The algorithm takes an application object application. This algorithm will return a list of fingerprint objects, possibly empty.

1. Let fingerprints be an empty list.
2. Let unprocessed fingerprints be the result of calling the [[GetOwnProperty]] internal method of application passing "fingerprints" as the argument.
3. If unprocessed fingerprints is an array, then for each potential fingerprint in unprocessed fingerprints:
   1. Let type be the result of calling the [[GetOwnProperty]] internal method of potential fingerprint passing "type" as an argument.
   2. If Type(type) is not "string", then issue a developer warning that the type is unsupported, and move on to the next item in unprocessed fingerprints (if any are left).
   3. Let value be the result of calling the [[GetOwnProperty]] internal method of potential fingerprint passing "value" as an argument.
   4. If Type(value) is not "string", then issue a developer warning that the type is unsupported, and move on to the next item in unprocessed fingerprints (if any are left).
   5. Let fingerprint be a fingerprint object, with its type member set to type and its value member set to value.
   6. Append fingerprint to fingerprints.
4. Otherwise, issue a developer warning that the type is unsupported.
5. Return fingerprints.

15.1 Media type registration

This section contains the required text for MIME media type registration with IANA.

The media type for a manifest is application/manifest+json.

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

Type name:

application

Subtype name:

manifest+json

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

Same as for application/json

Security and privacy considerations:

Issue 348

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

As the manifest format is JSON and will commonly be encoded using [ UNICODE], the security considerations described in [ ECMA-404] and [UNICODE-SECURITY] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest, implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [CSS-MIME], [ ECMAScript-MIME], [HTML].

As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.

As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [URL] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [UNICODE-SECURITY].

Developers need to be aware of the security considerations discussed throughout the [CSP3] specification, particularly in relation to making data: a valid source for the purpose of inlining a manifest. Doing so can enable XSS attacks by allowing a manifest to be included directly in the document itself; this is best avoided completely.

Applications that use this media type:

Web browsers

Additional information:

Magic number(s):

N/A

File extension(s):

.webmanifest

Macintosh file type code(s):

TEXT

Person & email address to contact for further information:

The Web Platform Working Group can be contacted at public-webapps@w3.org.

Intended usage:

COMMON

Restrictions on usage:

none

Author:

W3C's Web Platform Working Group.

Change controller:

W3C.

15.2 Link relation type registration

Relation Name:

manifest

Description:

Links to a manifest. A manifest provides developers with a centralized place to put metadata associated with a web application.

Reference:

https://www.w3.org/TR/appmanifest/

Notes:

Please refer to the steps for obtaining a manifest for details about how to fetch and apply a manifest.