Manifest Incubations

For advanced usages, the display_override member can be used to specify a custom fallback order of display mode values for developers to choose their preferred display mode.

The display_override member of the application manifest is a sequence of display mode values. This item represents the developer's preferred fallback chain for display modes. This field overrides the display member. If the user agent does not support any of the display modes specified here, then it falls back to considering the display member. See display modes for the algorithm steps.

The following steps are added to the processing extension-point in determining the web app's chosen display mode:

1. For each candidate_display_mode of manifest.display_override:
   1. If the user agent supports the candidate_display_mode, then return candidate_display_mode.

{
  "name": "Recipe Zone",
  "description": "All of the recipes!",
  "icons": [{
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }],
  "start_url": "/index.html",
  "display_override": ["minimal-ui"],
  "display": "standalone",
  "theme_color": "yellow",
  "background_color": "red"
}

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 Web Share Target API specification.

The note_taking member of the Web Application Manifest is an object that contains information related to note-taking. It has the following members:

• new_note_url

A user agent MAY use these members to treat the web application differently as an application with note-taking capabilities (e.g., integrate with operating system note-taking surfaces).

{
  "name": "My Note Taking App",
  "description": "You can take notes!",
  "icons": [{
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }],
  "start_url": "/index.html",
  "display": "standalone",
  "note_taking": {
    "new_note_url": "/new_note.html"
  }
}

The manifest's protocol_handlers member is an array of protocol handler descriptions that allows a web application to handle URL protocols.

On installation, a user agent SHOULD register protocol handlers with the Operating System via interactions that are consistent with:

• If there are multiple registered handlers for a protocol, the OS allows the user to select which app should open it, and also allows the user to set a default app.
• Clicking on a registered protocol will launch the registered application. If this is the web app, then execute the invoke a protocol handler steps 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.

The user_preferences member of the application manifest is an object that can be used to override values of manfiest members depending on which user preferences are set. It has the following members:

• color_scheme

The user agent SHOULD use the override values instead of the value of the corresponding member defined at the top level of the manifest.

To process the user_preferences member, given ordered map json, ordered map manifest, run the following during the processing extension-point in processing a manifest:

1. If json["user_preferences"] does not exist, return.
2. If the type of json["user_preferences"] is not ordered map, return.
3. Set manifest["user_preferences"] to a new ordered map.
4. Process the color_scheme member passing json["user_preferences"] and manifest["user_preferences"].

Each manifest override object is a generic object value that allows for certain manifest properties to be overridden within a particular context.

The structure of a manifest override object is as follows:

{
  "context_key": {
    "property": "new value"
  }
}

Each manifest property that accepts a manifest override object as its value will define the contexts it supports and which properties it supports overriding. User agents MUST ignore any contexts that are not supported by the property as well as any override properties not explicitly allowed within it.

When the manifest property’s context is applicable, the value of each allowable override will be used in place of the original value defined in the Manifest.

Redefined array items will be overridden in the order they are authored. When redefining objects (e.g., shortcuts, icons), authors will only be able to redefine specific properties of that object. In order to ensure all overrides are applied correctly, the order must match the original array (i.e., each shortcut must be redefined in order, as must their icons, if they also require re-definition).

When there is a conflict because two different properties are attempting to override the same value in their respective active contexts, the one defined last will win. By way of example, consider the following:

{
  "lang": "en-US",
  "icons": [
    {
      "src": "icon.png",
      "sizes": "128x128",
      "type": "image/png"
    }
  ],
  "translations": {
    "es": {
      "icons": [
        {
          "src": "icon-es.png"
        }
      ]
    }
  },
  "user_preferences": {
    "color_scheme": {
      "dark": {
        "icons": [
          {
            "src": "icon-dark.png"
          }
        ]
      }
    }
  }
}

In this example, if the user’s primary language is Español, but their preferred color scheme was set to "dark", the icon supplied would be the dark version and not the localized one. For this reason, it is imperative that properties taking a manifest override object as their value consider whether any other properties that also enable overrides should be able to be redefined within them. In the above example, the author’s intent would likely have been better realized if user_preferences was put before translations and the localized context block redefined the user_preferences value for that language:

{
  "lang": "en-US",
  "icons": [
    {
      "src": "icon.png",
      "sizes": "128x128",
      "type": "image/png"
    }
  ],
  "user_preferences": {
    "color_scheme": {
      "dark": {
        "icons": [
          {
            "src": "icon-dark.png"
          }
        ]
      }
    }
  },
  "translations": {
    "es": {
      "icons": [
        {
          "src": "icon-es.png"
        }
      ],
      "user_preferences": {
        "color_scheme": {
          "dark": {
            "icons": [
              {
                "src": "icon-es-dark.png"
              }
            ]
          }
        }
      }
    }
  },
  
}

User agents MAY ignore any override properties they do not support.

To apply a manifest override object, given ordered_map overrides, ordered map manifest, and array allowed_properties run the following:

1. Let allowed_overrides be a new ordered map.
2. For each member of overrides:
   1. If member is not in allowed_properties, continue.
   2. Set allowed_overrides[member] to |overrides[member]|.
3. Let overriden_manifest be the result of creating a new ordered map by merging manifest with allowed_overrides.
4. Set manifest to overriden_manifest.

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, directly invoking the steps to present an install prompt.
• 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 signals to warrant installation of the web application.

In any case, the user agent MUST NOT present an install prompt if the document is not installable.

The user agent MAY, at any time (only if the document is installable), 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 the user needing to interact with the user agent UI.

To present an install prompt:

1. Show some user-agent-specific UI, asking the user whether to proceed with installing the app. The result of this choice is either "accepted" or "dismissed".
2. Return result, and in parallel:
   1. If result is "accepted", run the steps to install the web application.

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 install prompt being presented or if the steps to install the web application are currently being executed, then abort this step.
3. Queue a task on the application life-cycle task source to do the following:
   1. Let mayShowPrompt be the result of fire an event named "beforeinstallprompt" at the top-level browsing context's relevant global object using the BeforeInstallPromptEvent interface, with steps to initialize the cancelable attribute to true.
   2. If mayShowPrompt is true, then the user agent MAY, in parallel, request to present an install prompt with event.

Events of this specification rely on the application life-cycle task source.

WebIDL[Exposed=Window]
interface BeforeInstallPromptEvent : Event {
  constructor(DOMString type, optional EventInit eventInitDict = {});
  Promise<PromptResponseObject> prompt();
};

dictionary PromptResponseObject {
  AppBannerPromptOutcome userChoice;
};

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

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}`);
  });
});

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

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.