diff --git a/index.html b/index.html index b1441dd11..61a23a553 100644 --- a/index.html +++ b/index.html @@ -287,6 +287,36 @@

and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.

+

+ A {{Document}} may either be installable or not. The initial + state of a document is not installable. +

+

+ At any time, the user agent MAY perform the steps to determine + installability of the document: +

+
    +
  1. Let manifest and manifest URL be the result + of obtaining the manifest. +
    2. +
  2. If obtaining the manifest results in an error, the user + agent MAY either: +
      +
    1. Fall back to using the top-level browsing context + {{Document}}'s metadata to to populate manifest in a + user-agent-specific way (e.g., setting + |manifest|.{{WebAppManifest/name}} to the document `title`) and considering the document + installable. +
      2. +
    2. Or, consider the document not installable. +
      3. +
    +
    3. +
  3. Otherwise, the {{Document}} MAY be considered installable + (at the user agent's discretion; see [[[#installability-signals]]]). +
    4. +

Authority of the manifest's metadata @@ -334,77 +364,52 @@

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. Let manifest and manifest URL be the values + that were created during steps to determine installability of the + document.
    3. -
  3. Then, in parallel: +
  4. If manifest URL exists, and the result of running + processing the `serviceworker` member with manifest + returns a valid registration, the user agent MAY:
      -
    1. Instantiate an installation process. -
      2. -
    2. Let manifest and manifest URL be the result of - obtaining the manifest. -
      3. -
    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. -
    4. If obtaining the manifest succeeds, and the result of - running 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. -
      2. Invoke Start Register with scope and - src members of the registration, a new - promise, client, manifest URL, - plus the type and update_via_cache - members of the registration, in which case the - state of the settled promise determines whether - the installation succeeded or not. -
        3. -
      +
    5. Let client be the top-level browsing + context {{Document}}'s relevant settings object, or + null if unavailable.
      6. -
    6. If the installation succeeded, queue a task on - the application life-cycle task source to fire an - event named appinstalled at the - window object. +
    7. Invoke Start Register with scope and + src members of the registration, a new + promise, client, manifest URL, + plus the type and update_via_cache + members of the registration. If the settled + promise is rejected, abort these steps.
    5. +
  5. Perform an unspecified sequence of actions to attempt to register + the web application in the user's operating system (e.g., create + shortcuts that launch the web application, register the application + in the system uninstall menu, etc.). If the installation fails (which + can be for any reason, for example, the OS denying permission to the + user agent to add an icon to the home screen of the device), abort + these steps. +
    6. +
  6. + Queue a task on the application life-cycle task + source to fire an event named appinstalled + at the the {{Window}} object of the top-level browsing + context for which the installation took place. +
+
+

Install prompts

@@ -414,41 +419,61 @@

  • 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. + 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 installability 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. +

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. + 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 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. + To present + an install prompt:

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

The steps to notify that an install prompt is available are given by the following algorithm: @@ -457,9 +482,10 @@

  • Wait until the {{Document}} of the top-level browsing context is completely loaded.
    • -
  • If there is already an installation process being - presented, terminate this - algorithm. +
  • If there is already an install prompt being presented or if + the steps to install the web application are currently being + executed, terminate this algorithm.
  • Queue a task on the application life-cycle task @@ -487,14 +513,15 @@

    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. + During the presentation of the install prompt, 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 @@ -507,7 +534,7 @@

    • -

    +

    Installability signals

    @@ -607,14 +634,13 @@

    If the BeforeInstallPromptEvent is not cancelled, the - user agent is allowed to present an automated install prompt - to the end-user. Canceling the default action (via present an install prompt + (specifically, an automated install prompt) to the end-user. + Canceling the default action (via preventDefault) prevents the user - agent from presenting an - automated install prompt. The user agent is free to run steps - to notify that an install prompt is available again at a later - time. + agent from presenting an install prompt. The user agent is + free to run steps to notify that an install prompt is + available again at a later time.

    The PromptResponseObject contains the result of calling @@ -728,8 +754,7 @@

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

    @@ -786,8 +811,8 @@

    attribute for the "appinstalled" event type. The interface used for these events is the Event interface [[DOM]]. This event is dispatched as a result of a - successful installation - (see the steps to install the web application). + successful installation (see the steps to install the web + application).