Page Visibility

W3C Recommendation 14 May 2013

This version:: http://www.w3.org/TR/2013/REC-page-visibility-20130514/
Latest version:: http://www.w3.org/TR/page-visibility/
Previous version:: http://www.w3.org/TR/2013/PR-page-visibility-20130219/
Editors:: Jatinder Mann, Microsoft Corp., <jmann@microsoft.com>; Arvind Jain, Google Inc., <arvind@google.com>

Please refer to the errata for this document, which may include some normative corrections.

Abstract

This specification defines a means for site developers to programmatically determine the current visibility state of the page in order to develop power and CPU 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 http://www.w3.org/TR/.

This is the W3C Recommendation of "Page Visibility". An implementation report, produced during the Candidation Recommendation phase in 2013, is available based on the Page Visibility test suite.

Please send comments to public-web-perf@w3.org (archived) with [PageVisibility] at the start of the subject line.

With the update of idlharness.js to support for the enumeration type used by the Page Visibility specification, the Director was satisfied by the evidence of stability of the Web IDL portions. The Director also noted that the specification relies on the partial interface definition of Document from the HTML5 specification, itself extending the Document definition provided in DOM4. This interface is also defined in the DOM Level 3 Recommendation. The nature of the extension itself as a pure extension that does not modify other portions of the Document interface and implementations of Page Visibility would not be impacted by changes in DOM4. The Director has determined that, due to the nature of these references, the current specification is sufficiently independent that it may advance to W3C Recommendation.

No changes to this document have been made since the previous version.

This document is produced by the Web Performance Working Group. The Web Performance Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document was produced by a group operating under the 5 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 contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

1 Introduction
2 Conformance requirements
3 Terminology
4 Page Visibility
5 Privacy
6 References
Acknowledgements

1 Introduction

This section is non-normative.

The Page Visibility specification defines a means for site developers to programmatically determine the current visibility of a document and be notified of visibility changes. Without knowing the visibility state of a page, web developers have been designing webpages as if they are always visible. This not only results in higher machine resource utilization, but it prevents web developers from making runtime decisions based on whether the webpage is visible to the user. Designing web pages with knowledge of the page visibility will allow for improved user experiences and power efficient sites.

With this interface, web applications may chose to alter behavior based on whether they are visible to the user or not. For example, this interface can be used to scale back work when the page is no longer visible. If a web based email client is visible, it may check the server for new messages every few seconds. When hidden it might scale checking email to every few minutes. This interface can also be used to provide better runtime user experience decisions not related to power management. For example, a puzzle game could be paused when the user no longer has the game visible. Further, this interface can be used by advertisers to not charge for ads that are not visible to users.

For example, the following script shows a theoretical web based email client checking for new messages every second without knowledge of the Page Visibility:

<!DOCTYPE html>
<html>
 <head>
  <script>
   var timer = 0;
   var PERIOD = 1000;

   function onLoad() {
       timer = setInterval(checkEmail, PERIOD);
   }

   function checkEmail() { 
       // Check server for new messages
   }

  </script>
 </head>
 <body onload="onLoad()">
 </body>
</html>

The script will always check for messages every second, even if the user is not actively viewing the page because it is not visible. This is an example of poor resource management.

Using the hidden attribute of the Document interface and the visibilitychange event, the page will be able to throttle checking messages to every minute when the page is no longer visible.

The following script show the theoretical web based email client checking for new messages every second when visible and every minute when not visible:

<!DOCTYPE html>
<html>
 <head>
  <script>
   var timer = 0;
   var PERIOD_VISIBLE = 1000;
   var PERIOD_NOT_VISIBLE = 60000;

   function onLoad() {
       timer = setInterval(checkEmail, (document.hidden) ? PERIOD_NOT_VISIBLE : PERIOD_VISIBLE);
       if(document.addEventListener) document.addEventListener("visibilitychange", visibilityChanged);
   }

   function visibilityChanged() {
       clearTimeout(timer);
       timer = setInterval(checkEmail, (document.hidden) ? PERIOD_NOT_VISIBLE : PERIOD_VISIBLE);
   }

   function checkEmail() { 
       // Check server for new messages
   }

  </script>
 </head>
 <body onload="onLoad()">
 </body>
</html>

2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

4 Page Visibility

4.1 Introduction

This section is non-normative.

This specification introduces an interface that provides Web applications with the means to programmatically determine the current visibility of a page and be notified of visibility changes.

4.2 Extensions to the `Document` interface

The HTML5 specification defines a partial Document interface [HTML5], which this specification extends:

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

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

`hidden` attribute

On getting, the hidden attribute MUST return true if the Document contained by the top level browsing context (root window in the browser's viewport) [HTML5] is not visible at all. The attribute MUST return false if the Document contained by the top level browsing context is at least partially visible on at least one screen.

If the defaultView of the Document is null, on getting, the hidden attribute MUST return true.

To accommodate accessibility tools that are typically full screen but still show a view of the page, when applicable, this attribute MAY return false when the User Agent is not minimized but is fully obscured by other applications.

Note

As examples, on getting, the hidden attribute returns true when:

The User Agent is minimized.
The User Agent is not minimized, but the page is on a background tab.
The User Agent is about to unload the page.
The User Agent is about to traverse to a session history entry.
The Operating System lock screen is shown.

Likewise, as examples, on getting, the hidden attribute returns false when:

The User Agent is not minimized and the page is on a foreground tab.
The User Agent is fully obscured by an Accessibility Tool, like a magnifier, but a view of the page is shown.

`visibilityState` attribute

On getting, visibilityState attribute MUST return one of the following DOMStrings or a vendor prefixed DOMString as defined in 4.5 Vendor Prefixes:

hidden,
visible,
prerender,
unloaded.

`hidden`

On getting, the visibilityState attribute MUST return the DOMString hidden if the Document contained by the top level browsing context is not visible at all on any screen.

If the defaultView of the Document is null, on getting, the visibilityState attribute MUST return the DOMString hidden.

To accommodate accessibility tools that are typically full screen but still show a view of the page, when applicable, on getting, the visibilityState attribute MAY return the DOMString visible, instead of hidden, when the User Agent is not minimized but is fully obscured by other applications.

Note

For example, in the following cases the visibilityState attribute would return the DOMString hidden:

The User Agent is minimized.
The User Agent is not minimized, but the page is on a background tab.
The Operating System lock screen is shown.

`visible`

On getting, the visibilityState attribute MUST return the DOMString visible if the Document contained by the top level browsing context is at least partially visible at on at least one screen. This is the same condition under which the hidden attribute is set to false.

To accommodate accessibility tools that are typically full screen but still show a view of the page, when applicable, on getting, the visibilityState attribute MAY return the DOMString visible when the User Agent is not minimized but is fully obscured by other applications.

`prerender`

On getting, the visibilityState attribute MAY return the DOMString prerender if the Document contained by the top level browsing context is loaded off-screen and is not visible. User Agent support of the prerender return value of the visibilityState attribute is optional.

`unloaded`

On getting, the visibilityState attribute SHOULD return the DOMString unloaded if the User Agent is to unload the Document contained by the top level browsing context. User Agent support of the unloaded return value of the visibilityState attribute is optional.

4.3 The `visibilitychange` event

The User Agent MUST fire the visiblitychange event at the Document when the User Agent determines that the visibility of the Document contained by the top level browsing context has changed.

4.4 Processing Model

When the User Agent determines that the visibility of the Document contained by the top level browsing context has changed, the User Agent MUST run the following steps.

If the Document contained by the top level browsing context is now at least partially visible on at least one screen,

If traversing to a session history entry, run the now visible algorithm before running the step to fire the pageshow event.
Otherwise, queue a task that runs the now visible algorithm.

Else if the Document contained by the top level browsing context is now not visible or if the user agent is to unload the Document,

If the user agent is to unload the Document, run the now hidden algorithm during the unloading document visibility change steps,
Otherwise, queue a task that runs the now hidden algorithm.

The now visible algorithm runs the following steps synchronously:

Set the hidden attribute to false.
Set the visibilityState attribute to visible.
Fire a simple event named visiblitychange that bubbles, isn't cancelable, and has no default action, at the Document.

The now hidden algorithm runs the following steps synchronously:

Set the hidden attribute to true.
Set the visibilityState attribute to hidden. If the user agent is to unload the Document, set the visibilityState attribute to unloaded. Setting visibilityState attribute to unloaded instead of hidden is optional.
Fire a simple event named visiblitychange that bubbles, isn't cancelable, and has no default action, at the Document.

4.5 Vendor Prefixes

Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed, e.g., for experimental purposes, vendors MUST use the following extension mechanisms:

If an extension to the visibilityState attribute return value is needed for an experimental visibility state, User Agents MUST update the VisibilityState enum with a DOMString that uses the following convention:

[vendorprefix]-[name]

Where,

[vendorprefix] is a non-capitalized name that identifies the vendor,
[name] is a non-capitalized name given to the visibility state,
and the above names are in ASCII.

5 Privacy

The Page Visibility API enables third party content on a web page to determine the visibility of the Document contained by the top level browsing context with higher precision compared to existing mechanisms, like focus or blur events. However, for practical considerations, the additional exposure is not substantial.

6 References

[IETF RFC 2119]: Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[HTML5]: HTML5, Robin Berjon et al., Editors. World Wide Web Consortium, December 2012. This version of the HTML5 is available from http://www.w3.org/TR/html5/. The latest editor's draft of HTML5 is available at http://www.w3.org/html/wg/drafts/html/CR/.
[Web IDL]: Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.

Acknowledgements

We would like to sincerely thank Karen Anderson, Nic Jansma, Alex Komoroske, Cameron McCormack, James Robinson, Jonas Sicking, Kyle Simpson, Jason Weber, and Boris Zbarsky to acknowledge their contributions to this work.