@@ -296,6 +296,36 @@ <h2>
296296 and again as an example, the user agent could < a > install</ a > the web
297297 application into a list of bookmarks within the user agent itself.
298298 </ p >
299+ < p >
300+ A {{Document}} may either be < dfn > installable</ dfn > or not. The initial
301+ state of a document is not < a > installable</ a > .
302+ </ p >
303+ < p >
304+ At any time, the user agent MAY perform the < dfn > steps to determine
305+ installability of the document</ dfn > :
306+ </ p >
307+ < ol >
308+ < li > Let < var > manifest</ var > and < var > manifest URL</ var > be the result
309+ of < a > obtaining the manifest</ a > .
310+ </ li >
311+ < li > If < a > obtaining the manifest</ a > results in an error, the user
312+ agent MAY either:
313+ < ol >
314+ < li > Fall back to using the < a > top-level browsing context</ a >
315+ {{Document}}'s metadata to to populate < var > manifest</ var > in a
316+ user-agent-specific way (e.g., setting
317+ |manifest|.{{WebAppManifest/name}} to the document < a data-cite =
318+ "HTML#the-title-element "> `title`</ a > ) and considering the document
319+ < a > installable</ a > .
320+ </ li >
321+ < li > Or, consider the document not < a > installable</ a > .
322+ </ li >
323+ </ ol >
324+ </ li >
325+ < li > Otherwise, the {{Document}} MAY be considered < a > installable</ a >
326+ (at the user agent's discretion; see [[[#installability-signals]]]).
327+ </ li >
328+ </ ol >
299329 < section >
300330 < h3 >
301331 Authority of the manifest's metadata
@@ -343,77 +373,52 @@ <h3>
343373 < h3 >
344374 Installation process
345375 </ h3 >
346- < p >
347- An < dfn > installation process</ dfn > is an attempt by the user agent to
348- < a > install</ a > a web application. The details of such a process
349- (i.e., the display of an install < abbr > UI</ abbr > , and any resulting
350- < abbr > IO</ abbr > operations of the host < abbr > OS</ abbr > ) are left up
351- to implementers. Implementers need to be aware that there are
352- < a href ="#installation-sec "> privacy and security considerations</ a >
353- that directly relate to the < a > installation process</ a > .
354- </ p >
355- < p >
356- For the purpose of this specification, the < dfn > installation
357- succeeded</ dfn > once the < a > installation process</ a > succeeds in
358- < a > installing</ a > the web application (e.g., an icon was successfully
359- placed onto the device's homescreen). If the end-user cancels the
360- installation process (even if they < a > manually</ a > triggered it, and
361- then changed their minds), then the < dfn > installation was
362- canceled</ dfn > . Otherwise, the < dfn > installation failed</ dfn > .
363- Reasons for installation failure can include, for example, the OS
364- denying permission to the user agent to add an icon to the homescreen
365- of the device and the end-user rejecting the installation.
366- </ p >
367376 < p >
368377 The < dfn > steps to install the web application</ dfn > are given by the
369378 following algorithm:
370379 </ p >
371380 < ol >
372- < li > Let < var > window </ var > be the {{Window}} object of the
373- < a > top-level browsing context </ a > for which the user agent will
374- attempt installation .
381+ < li > Let < var > manifest </ var > and < var > manifest URL </ var > be the values
382+ that were created during < a > steps to determine installability of the
383+ document </ a > .
375384 </ li >
376- < li > Then, < a > in parallel</ a > :
385+ < li > If < var > manifest URL</ var > exists, and the result of running < a >
386+ processing the `serviceworker` member</ a > with < var > manifest</ var >
387+ returns a valid < var > registration</ var > , the user agent MAY:
377388 < ol >
378- < li > Instantiate an < a > installation process</ a > .
379- </ li >
380- < li > Let < a > manifest</ a > and < a > manifest URL</ a > be the result of
381- < a > obtaining the manifest</ a > .
382- </ li >
383- < li > If < a > obtaining the manifest</ a > results in an error, a user
384- agent can, at this point, fall back to using the < a > top-level
385- browsing context</ a > {{Document}}'s metadata to populate an
386- < a > installation process</ a > 's UI.
387- </ li >
388- < li > If < a > obtaining the manifest</ a > succeeds, and the result of
389- running < a > processing the `serviceworker` member</ a > with
390- < a > manifest</ a > returns a valid < var > registration</ var > , a user
391- agent can at this point:
392- < ol >
393- < li > Let < var > client</ var > be the < a > top-level browsing
394- context</ a > {{Document}}'s < a > relevant settings object</ a > ,
395- or < code > null</ code > if unavailable.
396- </ li >
397- < li > Invoke < a > Start Register</ a > with < var > scope</ var > and
398- < var > src</ var > members of the < var > registration</ var > , a new
399- < var > promise</ var > , < var > client</ var > , < a > manifest URL</ a > ,
400- plus the < var > type</ var > and < var > update_via_cache</ var >
401- members of the < var > registration</ var > , in which case the
402- state of the settled < var > promise</ var > determines whether
403- the < a > installation succeeded</ a > or not.
404- </ li >
405- </ ol >
389+ < li > Let < var > client</ var > be the < a > top-level browsing
390+ context</ a > {{Document}}'s < a > relevant settings object</ a > , or
391+ < code > null</ code > if unavailable.
406392 </ li >
407- < li > If the < a > installation succeeded</ a > , < a > queue a task</ a > on
408- the < a > application life-cycle task source</ a > to < a > fire an
409- event</ a > named < code > appinstalled</ code > at the
410- < var > window</ var > object.
393+ < li > Invoke < a > Start Register</ a > with < var > scope</ var > and < var >
394+ src</ var > members of the < var > registration</ var > , a new
395+ < var > promise</ var > , < var > client</ var > , < var > manifest URL</ var > ,
396+ plus the < var > type</ var > and < var > update_via_cache</ var >
397+ members of the < var > registration</ var > . If the settled
398+ < var > promise</ var > is rejected, abort these steps.
411399 </ li >
412400 </ ol >
413401 </ li >
402+ < li > Perform an unspecified sequence of actions to attempt to register
403+ the web application in the user's operating system (e.g., create
404+ shortcuts that launch the web application, register the application
405+ in the system uninstall menu, etc.). If the installation fails (which
406+ can be for any reason, for example, the OS denying permission to the
407+ user agent to add an icon to the home screen of the device), abort
408+ these steps.
409+ </ li >
410+ < li >
411+ < a > Queue a task</ a > on the < a > application life-cycle task
412+ source</ a > to < a > fire an event</ a > named < code > appinstalled</ code >
413+ at the the {{Window}} object of the < a > top-level browsing
414+ context</ a > for which the installation took place.
415+ </ li >
414416 </ ol >
417+ < div class ="issue " data-number ="789 "> </ div >
415418 </ section >
416419 < section >
420+ <!-- TODO(mgiuca): Move this section up above Installation process. (In
421+ a separate PR; otherwise it would be too hard to review.) -->
417422 < h2 >
418423 Install prompts
419424 </ h2 >
@@ -423,41 +428,61 @@ <h2>
423428 </ p >
424429 < ul >
425430 < li > An end-user can < dfn data-lt ="manual installation "> manually</ dfn >
426- trigger the < a > installation process</ a > through the user agent's
427- < abbr > UI</ abbr > .
428- </ li >
429- < li > The < a > installation process</ a > can occur through an
430- < dfn > automated install prompt</ dfn > : that is, a < abbr > UI</ abbr > that
431- the user agent presents to the user when, for instance, there are
432- sufficient < a > installability signals</ a > to warrant
433- < a > installation</ a > of the web application.
434- </ li >
435- < li > The < a > installation process</ a > can occur through a
436- < dfn > site-triggered install prompt</ dfn > : the site can
437- programmatically request that the user agent present an install
438- prompt to the user. The user agent MAY restrict the availability of
439- this feature to cases where, for instance, there are sufficient
440- < a > installability signals</ a > to warrant < a > installation</ a > of the
441- web application.
431+ trigger the installation process through the user agent's
432+ < abbr title ="User Interface "> UI</ abbr > , directly invoking the steps
433+ to < a > present an install prompt</ a > .
434+ </ li >
435+ < li > The installation process can occur through an < dfn > automated
436+ install prompt</ dfn > : that is, a UI that the user agent presents to
437+ the user when, for instance, there are sufficient < a > installability
438+ signals</ a > to warrant < a > installation</ a > of the web application.
439+ </ li >
440+ < li > The installation process can occur through a < dfn > site-triggered
441+ install prompt</ dfn > : the site can programmatically request that the
442+ user agent present an install prompt to the user. The user agent MAY
443+ restrict the availability of this feature to cases where, for
444+ instance, there are sufficient < a > installability signals</ a > to
445+ warrant < a > installation</ a > of the web application.
442446 </ li >
443447 </ ul >
448+ < p >
449+ In any case, the user agent MUST NOT < a > present an install prompt</ a >
450+ if the document is not < a > installable</ a > .
451+ </ p >
444452 < p >
445453 Prior to presenting an < a > automated install prompt</ a > , a user agent
446454 MUST run the < a > steps to notify that an install prompt is
447455 available</ a > , to give the site the opportunity to prevent the
448456 default action (which is to install the application). Alternatively,
449- the user agent MAY run the < a > steps to notify that an install prompt
450- is available</ a > at any time, giving the site the opportunity to show
451- a < a > site-triggered install prompt</ a > without automatically showing
452- the prompt.
457+ the user agent MAY, at any time (only if the document is
458+ < a > installable</ a > ), run the < a > steps to notify that an install
459+ prompt is available</ a > at any time, giving the site the opportunity
460+ to show a < a > site-triggered install prompt</ a > without automatically
461+ showing the prompt.
453462 </ p >
454463 < p >
455- In either case, when a user agent < dfn data-lt =
456- "present an install prompt|presenting an install prompt "> presents an
457- install prompt</ dfn > , the end-user's choice is represented either
458- "accepted" or "dismissed". These values are represented in the API of
459- this specification via the < a > AppBannerPromptOutcome</ a > enum.
464+ To < dfn data-lt =
465+ "presenting an install prompt|presentation of the install prompt "> present
466+ an install prompt</ dfn > :
460467 </ p >
468+ < ol >
469+ < li > Show some user-agent-specific UI, asking the user whether to
470+ proceed with installing the app. See < a href =
471+ "#installation-sec "> privacy and security considerations</ a > for
472+ recommendations relating to this UI. The < var > result</ var > of this
473+ choice is either < a data-link-for =
474+ "AppBannerPromptOutcome "> accepted</ a > or < a data-link-for =
475+ "AppBannerPromptOutcome "> dismissed</ a > .
476+ </ li >
477+ < li > Return < var > result</ var > , and < a > in parallel</ a > :
478+ < ol >
479+ < li > If < var > result</ var > is < a data-link-for =
480+ "AppBannerPromptOutcome "> accepted</ a > , run the < a > steps to
481+ install the web application</ a > .
482+ </ li >
483+ </ ol >
484+ </ li >
485+ </ ol >
461486 < p >
462487 The < dfn > steps to notify that an install prompt is available</ dfn >
463488 are given by the following algorithm:
@@ -466,9 +491,10 @@ <h2>
466491 < li > Wait until the {{Document}} of the < a > top-level browsing
467492 context</ a > is < a > completely loaded</ a > .
468493 </ li >
469- < li > If there is already an < a > installation process</ a > being
470- < a data-lt ="present an install prompt "> presented</ a > , terminate this
471- algorithm.
494+ < li > If there is already an < a data-lt =
495+ "present an install prompt "> install prompt being presented</ a > or if
496+ the < a > steps to install the web application</ a > are currently being
497+ executed, terminate this algorithm.
472498 </ li >
473499 < li >
474500 < a > Queue a task</ a > on the < a > application life-cycle task
@@ -496,14 +522,15 @@ <h3 id="installation-sec">
496522 Privacy and security considerations
497523 </ h3 >
498524 < p >
499- During the < a > installation process</ a > , it is RECOMMENDED that the
500- user agent allow the end-user to inspect the icon, name, < a > start
501- URL</ a > , origin, etc. pertaining to a web application. This is to
502- give an end-user an opportunity to make a conscious decision to
503- approve, and possibly modify, the information pertaining to the web
504- application before installing it. This also gives the end-user an
505- opportunity to discern if the web application is spoofing another web
506- application, by, for example, using an unexpected icon or name.
525+ During the < a > presentation of the install prompt</ a > , it is
526+ RECOMMENDED that the user agent allow the end-user to inspect the
527+ icon, name, < a > start URL</ a > , origin, etc. pertaining to a web
528+ application. This is to give an end-user an opportunity to make a
529+ conscious decision to approve, and possibly modify, the information
530+ pertaining to the web application before installing it. This also
531+ gives the end-user an opportunity to discern if the web application
532+ is spoofing another web application, by, for example, using an
533+ unexpected icon or name.
507534 </ p >
508535 < p >
509536 It is RECOMMENDED that user agents prevent other applications from
@@ -516,7 +543,7 @@ <h3 id="installation-sec">
516543 </ p >
517544 </ section >
518545 < section class ="informative ">
519- < h3 >
546+ < h3 id =" installability-signals " >
520547 Installability signals
521548 </ h3 >
522549 < p >
@@ -616,14 +643,13 @@ <h3>
616643 </ p >
617644 < div class ="note ">
618645 If the < a > BeforeInstallPromptEvent</ a > is < em > not</ em > cancelled, the
619- user agent is allowed to < a data-lt =
620- " presents an install prompt " > present an automated install prompt</ a >
621- to the end-user. Canceling the default action (via < a data-cite =
646+ user agent is allowed to < a > present an install prompt </ a >
647+ (specifically, an < a > automated install prompt</ a > ) to the end-user.
648+ Canceling the default action (via < a data-cite =
622649 "DOM#dom-event-preventdefault "> preventDefault</ a > ) prevents the user
623- agent from < a data-lt ="presents an install prompt "> presenting an
624- automated install prompt</ a > . The user agent is free to run < a > steps
625- to notify that an install prompt is available</ a > again at a later
626- time.
650+ agent from < a > presenting an install prompt</ a > . The user agent is
651+ free to run < a > steps to notify that an install prompt is
652+ available</ a > again at a later time.
627653 </ div >
628654 < p data-dfn-for ="PromptResponseObject ">
629655 The < dfn > PromptResponseObject</ dfn > contains the result of calling
737763 </ h4 >
738764 < p >
739765 The < dfn > AppBannerPromptOutcome</ dfn > enum's values represent the
740- outcomes from < a data-lt ="presents an install prompt "> presenting
741- the end-user with an install prompt</ a > .
766+ outcomes from < a > presenting an install prompt</ a > .
742767 </ p >
743768 < dl data-dfn-for ="AppBannerPromptOutcome ">
744769 < dt >
795820 attribute</ a > for the "< dfn > appinstalled</ dfn > " event type. The
796821 interface used for these events is the < a > < code > Event</ code >
797822 interface</ a > [[DOM]]. This event is dispatched as a result of a
798- < a data-lt =" installation succeeded " > successful installation </ a >
799- (see the < a > steps to install the web application</ a > ).
823+ successful installation (see the < a > steps to install the web
824+ application</ a > ).
800825 </ p >
801826 </ section >
802827 < section data-dfn-for ="Window ">
0 commit comments