Page Visibility

W3C

W3C Candidate Proposed Recommendation 26 July 2012 19 February 2013

This version:
http://www.w3.org/TR/2012/CR-page-visibility-20120726/ http://www.w3.org/TR/2013/PR-page-visibility-20130219/
Latest version:
http://www.w3.org/TR/page-visibility/
Latest Editor's Draft: Previous version:
http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html http://www.w3.org/TR/2012/CR-page-visibility-20120726/
Previous version: Latest Editor's Draft:
http://www.w3.org/TR/2011/WD-page-visibility-20110721/ http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html
Editors:
Jatinder Mann , Microsoft Corp. , < >
Arvind Jain , Google Inc. , < >

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 Proposed Recommendation of "Page Visibility". W3C publishes a Candidate technical report as a Proposed Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. The entrance criteria a mature technical report that has received wide review for this document technical soundness and implementability and to enter request final endorsement from the W3C Advisory Committee. Proposed Recommendation stage status is to have a minimum of two independent and interoperable user agents that implementation all the features of this specification, which will be determined by passing the user agent tests defined described in section 7.1.1 of the test suite developed by the Working Group. Process Document .

The Working Group does not expect to advance to Proposed Recommendation prior to 1 November 2012 . A preliminary implementation report is available W3C Membership and will be updated during other interested parties are invited to review the Candidate Recommendation period. This is a work in progress document and may change without any notices. The Working Group intends to gain implementation experience before recommending that implementations remove their vendor prefixes. Please send comments to public-web-perf@w3.org ( archived ) with [PageVisibility] at the start of the subject line by 1 November 2012 . line. Advisory Committee Representatives should consult their WBS questionnaires . The deadline for review and comments is 19 March 2013. Note that substantive technical comments were expected during the Last Call review period that ended 18 August 2011.

Please note that the advancement to Recommendation is pending until the update of idlharness.js with support for the enumeration type used by this specification.

A diff document with the previous draft is also available.

Please see the Working Group's implementation report. At this stage, the Working Group encourages implementations of this specification to remove their vendor prefixes.

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 .

You can find the latest Editor's Draft of this document in the W3C's Mercurial repository , which is updated on a regular basis. Publication as a Candidate Proposed 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 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 .

Table of Contents

  1. 1 Introduction
  2. 2 Conformance requirements
  3. 3 Terminology
  4. 4 Page Visibility
    1. 4.1 Introduction
    2. 4.2 Extensions to the Document interface
    3. 4.3 The visibilitychange event
    4. 4.4 Processing Model
    5. 4.5 Vendor Prefixes
  5. 5 Privacy
  6. 6 References
  7. 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 VisibilityStateDOMString visibilityState; 
  // "hidden", "visible", "prerender", "unloaded"
};

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:

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

visibilityState attribute

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

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 :

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,

  1. If traversing to a session history entry , run the following steps now visible algorithm before running the step to fire the pageshow event.

  2. Queue Otherwise, queue a task that runs the following steps synchronously. Set the hidden attribute to false . Set the visibilityState attribute to now visible . Fire a simple event named visiblitychange that bubbles, isn't cancelable, and has no default action, at the Document 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 ,

  1. If traversing from a session history entry , run the following steps after running the steps to fire the pagehide event. If the user agent is to unload the Document , run the following steps now hidden algorithm during the unloading document visibility change steps ,

  2. Queue Otherwise, queue a task that runs the now hidden algorithm .

The now visible algorithm runs the following steps synchronously:

  1. Set the hidden attribute to false .

  2. Set the visibilityState attribute to visible .

  3. 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:

  1. Set the hidden attribute to true .

  2. Set the visibilityState attribute to hidden . If the user agent is to unload the Document , set the visibilityState attribute to unloaded . This step Setting visibilityState attribute to unloaded instead of hidden is optional.

  3. 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, on getting User Agents MUST update the visibilityState VisibilityState attribute, vendors MUST return enum with a DOMString that uses the following convention:

[vendorprefix]-[name]

Where,

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 , Ian Hickson, Editor. Robin Berjon et al., Editors. World Wide Web Consortium, March 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://dev.w3.org/html5/spec/. 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.