Page Visibility Level 2 (original) (raw)

Abstract

This specification defines a means to programmatically determine the visibility state of a document. This can aid in the development of resource efficient web applications.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Page Visibility Level 2 replaces the first version of [PAGE-VISIBILITY] and includes:

The Working Group expects to demonstrate 2 implementations of the features listed in this specification by the end of the Candidate Recommendation phase.

This document was published by the Web Performance Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them topublic-web-perf@w3.org (subscribe,archives).W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 10 January 2017. All comments are welcome.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the5 February 2004 W3C Patent Policy.W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes containsEssential Claim(s) must disclose the information in accordance withsection 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

  1. 1. Introduction
  2. 2. Conformance
  3. 3. Examples of usage
  4. 4. Visibility states and the VisibilityState enum
  5. 5. Extensions to the Document interface
    1. 5.1 hidden attribute
    2. 5.2 visibilityState attribute
    3. 5.3 onvisiblitychange event handler
  6. 6. Reacting to visibilitychange changes
  7. 7. Privacy and Security
  8. 8. Terminology
  9. A. Acknowledgments
  10. B. References
  11. B.1 Normative references
  12. B.2 Informative references

1. Introduction

This section is non-normative.

The Page Visibility API defines a means to programmatically determine the visibility state of a top level browsing context, and to be notified if the visibility state changes. Without knowing the visibility state of a page, web developers have been designing web pages as if they are alwaysvisible. This not only results in higher machine resource utilization, but it prevents web developers from making runtime decisions based on whether the web page is visible to the user. Designing web pages with knowledge of the page's visibility state can result in improved user experiences and power efficient sites.

With this API, web applications can choose to alter their behavior based on whether they are visible to the user or not. For example, this API can be used to scale back work when the page is no longer visible.

2. Conformance

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 and MUST are to be interpreted as described in [RFC2119].

3. Examples of usage

This section is non-normative.

To improve the user experience and optimize CPU and power efficiency the application could autoplay a video when the application isvisible, and automatically pause the playback when the application is hidden:

Example 1: Visibility-aware video playback

var videoElement = document.getElementById("videoElement");

if (document.visibilityState == "prerender") {

}

if (document.visibilityState == "visible") { videoElement.play(); }

function handleVisibilityChange() { if (document.visibilityState == "hidden") { videoElement.pause(); } else { videoElement.play(); } }

document.addEventListener('visibilitychange', handleVisibilityChange, false);

Similar logic can be applied to intellegently pause and resume, or throttle, execution of application code such as animation loops, analytics, and other types of processing. By combining thevisibilityState attribute of the Document interface and the visibilitychange event, the application is able to both query and listen to page visibility events to deliver a better user experience, as well as improve efficiency and performance of its execution.

4. Visibility states and the VisibilityState enum

The Document of the top level browsing context can be in one of the following visibility states:

hidden

The Document is not visible at all on any screen.

visible

The Document is at least partially visible on at least one screen. This is the same condition under which thehidden attribute is set to false.

prerender

The Document is loaded in the prerender mode and is not yet visible.

The visibility states are reflected in the API via theVisibilityState enum.

enum VisibilityState { "hidden", "visible", "prerender" };

5. Extensions to the Document interface

This specification extends the [HTML51] Document interface:

partial interface Document { readonly attribute boolean hidden; readonly attribute VisibilityState visibilityState; attribute EventHandler onvisibilitychange; };

5.1 hidden attribute

On getting, the hidden attribute MUST run the steps to determine if the document is hidden:

  1. If steps to determine the visibility state returnvisible, then return false.
  2. Otherwise, return true.

Note

Support for hidden attribute is maintained for historical reasons. Developers should usevisibilityState where possible.

5.2 visibilityState attribute

On getting, the visibilityState attribute the user agent_MUST_ run the steps to determine the visibility state:

  1. Let doc be the Document of the top level browsing context.
  2. If the defaultView of doc isnull, return hidden.
  3. Otherwise, return the VisibilityState value that best matches the visibility state of doc:
    1. If doc was prerendered [RESOURCE-HINTS] and has not previously transitioned to "visible", return "prerender".
    2. Return "visible" if:
      1. The user agent is not minimized and doc is the foreground tab.
      2. The user agent is fully obscured by an accessibility tool, like a magnifier, but a view of the doc is shown.
    3. Return "hidden" if:
      1. The user agent is minimized.
      2. The user agent is not minimized, but doc is on a background tab.
      3. The user agent is to unload doc.
      4. The Operating System lock screen is shown.

To accommodate assistive technologies that are typically full screen but still show a view of the page, when applicable, on getting, thevisibilityState attribute MAY returnvisible, instead of hidden, when the user agent is not minimized but is fully obscured by other applications.

5.3 onvisiblitychange event handler

onvisibilitychange is an event handler IDL attribute for the visibilitychange event type.

6. Reacting to visibilitychange changes

The task source for these tasks is the user interaction task source.

When the user agent determines that the visibility of theDocument of the top level browsing context has changed, the user agent MUST run the following steps:

  1. Let doc be the Document of the top level browsing context.
  2. If doc is now visible:
    1. If traversing to a session history entry, run the now visible algorithm before running the step to fire thepageshow event.
    2. Otherwise, queue a task that runs the now visible algorithm.
  3. Else if doc is now not visible, or if the user agent is to unload doc:
    1. If the user agent is to unload the Document, run the now hidden algorithm during the unloading document visibility change steps.
    2. Otherwise, queue a task that runs the now hidden algorithm.

The now visible algorithm runs the following steps synchronously:

  1. Let doc be the Document of the top level browsing context.
  2. Fire a simple event named visibilitychange that bubbles, isn't cancelable, and has no default action, at thedoc.

The now hidden algorithm runs the following steps synchronously:

  1. Let doc be the Document of the top level browsing context.
  2. Fire a simple event named visibilitychange that bubbles, isn't cancelable, and has no default action, at thedoc.

7. Privacy and Security

The Page Visibility API enables developers to know when aDocument is visible or in focus. Existing mechanisms, such as the focus and blur events, when attached to the Window object already provide a mechanism to detect when the Document is the active document; the unload event provides a notification that the page is being unloaded. This API extends these capabilities by also exposing the prerender state of the Document—see [RESOURCE-HINTS] security and privacy section for relevant considerations and best practices on the use of prerender—and unifies all of the above in a single API to simplify development of visibility-aware and efficient applications.

8. Terminology

The following concepts and interfaces are defined in the [HTML51] specification:

The [DOM4] specification defines how to fire a simple event.

A. Acknowledgments

Thanks to Alex Komoroske, Arvind Jain, Boris Zbarsky, Cameron McCormack, James Robinson, Jason Weber, Jonas Sicking, Karen Anderson, Kyle Simpson, Nat Duca, Nic Jansma, Philippe Le Hegaret, and Todd Reifsteck for their contributions to this work.

B. References

B.1 Normative references

[DOM4]

Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: https://www.w3.org/TR/dom/

[HTML51]

Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. HTML 5.1. 1 November 2016. W3C Recommendation. URL: https://www.w3.org/TR/html51/

[RESOURCE-HINTS]

Ilya Grigorik. W3C. Resource Hints. 27 May 2016. W3C Working Draft. URL: https://www.w3.org/TR/resource-hints/

[RFC2119]

S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

B.2 Informative references

[PAGE-VISIBILITY]

Jatinder Mann; Arvind Jain. W3C. Page Visibility (Second Edition). 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/