Copyright
© 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability,
trademark
and document
use rules apply.2011
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.
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/.
W3C publishes a
Candidate
Recommendation to indicate that the document is believed to be
stable and to encourage implementation by the ThisLastCallWorkingdeveloper community.
Draft
The entrance criteria for this document to enter the Proposed
Recommendation stage is to have a minimum of two independent and
interoperable user agents that implementation all the PageVisibilityfeatures of
this specification, which will be determined by passing the user
agent tests defined in the test suite developed by the Working Group.
specification.
The Working Group does not expect to advance to Proposed Recommendation prior to . A preliminary implementation report is available and will be updated during the Candidate Recommendation period. This is a work in progress 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 .
A diff document with the previous draft is available.
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 WorkingCandidate 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.Draft
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.
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 adevelopermustdesignthedevelopers
have been designing webpages as if webpageitthey 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.is
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.mail
For example, the following script shows a theoretical web based email client checking for new Javascriptmessages every second without knowledge of
the Page Visibility:emails
<!DOCTYPE html> <html> <head> <script> var timer = 0; var PERIOD = 1000; function onLoad() { timer = setInterval(checkEmail, PERIOD); } function checkEmail() { // Check server for newmessages } </script> </head> <body onload="onLoad()"> </body> </html>emails
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.emails
Using the
attribute of the Document
interface and the DocumentVisibilityhiddeninterface,visibilitychange
event,
the page will be able to throttle checking messages to every minute when the
page is no longer visible.email
The following script show the theoretical web based email client checking for new messages every second when visible and every minute when not visible:emails
<!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 newmessages } </script> </head> <body onload="onLoad()"> </body> </html>emails
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]
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
".
This section is usedtorefernon-normative.to
This specification introduces an interface that provides Web applications
with the APIsetmademeans to availablescriptsinWebapplications,anddoesnotnecessarilyprogrammatically determine the implycurrent visibility of existenceanactualDocumentobjectorofanyotherNodeobjectsasdefinedintheDOMCorespecifications.ADOMattributeissaidtobegettingwhenitsvalueisbeingretrieved(suchasbyauthorscript),andissaidtobesettingwhenanewvalueisassignedtoit.Theterm"JavaScript"isusedtorefertoECMA-262,ratherthantheofficialtermECMAScript,sincethetermJavaScriptismorewidelyknown.4PageVisibility4.1IntroductionThissectionisnon-normativeThisspecificationintroducesaninterfacethatprovidesWebapplicationswiththemeanstoprogrammaticallydeterminethecurrentvisibilityofapageandbea page
and be notified of visibility changes.notified
Document
interface
The HTML5 specification defines a
partial Document
interface DocumentVisibility[HTML5], which this specification
extends:
[NoInterfaceObject]
partial interfaceDocument {DocumentVisibilityconstDOMStringPAGE_HIDDEN="hidden";constDOMStringPAGE_VISIBLE="visible";constDOMStringPAGE_PREVIEW=readonly attribute boolean hidden; readonly attribute"preview";unsignedDOMString visibilityState; // "hidden", "visible", "prerender", "unloaded" };short
Document implements DocumentVisibility;hidden
attribute On getting, the Thishidden
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. returnsThe attribute ThisMUST return false if the Document contained by the
top level browsing context
is at least partially visible on at least one screen.
returns
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.may
As examples, on getting, the hidden
attribute returns true when:
Likewise, as examples, on getting, the hidden
attribute returns false when:
visibilityState
attribute document.PAGE_HIDDENOn getting, ThisvisibilityState
attribute MUST return
one of the following mustDOMString
s 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 document.PAGE_HIDDENDOMString
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, thisconstantmaynotbeon getting, the returnedvisibilityState
attribute MAY return
the DOMString
visible
, instead of hidden
, when the User Agent
is not minimized but is fully obscured by other applications.
For example, in the following cases the visibilityState
attribute would return the document.PAGE_HIDDENDOMString
hidden
:
document.PAGE_VISIBLE Thisvisible
On getting, the visibilityState
attribute MUST return mustthe document.PAGE_VISIBLEDOMString
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.
ThisconstantisnotreturnediftheDocumentcontainedbythetoplevelbrowsingcontextisnotvisible,however,apreviewoftheDocumentisTo accommodate accessibility tools that are typically full screen but still show a
view of the page, when applicable, visible.thisconstantmaybeon getting, the returnedvisibilityState
attribute MAY return
the DOMString
visible
when the User Agent
is not minimized but is fully obscured by other applications.
document.PAGE_PREVIEW This attribute is optional. Thisprerender
On getting, the visibilityState attribute MAY return maythe document.PAGE_PREVIEWDOMString
prerender
if the
Document contained by the
top level browsing context
is notvisibleatloaded off-screen and allais not visible. User Agent support of the previewprerender
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.
visible.
visibilitychange
event
The User Agent MUST fire the visibilitychangevisiblitychange
event at the
Document when the User Agent determines that the visibility of the Document contained by the
top level browsing context
has changed.
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 following steps before running the step to fire the pageshow
event.
Queue a task that 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.
Else if the Document contained by the
top level browsing context
is firedanynow not visible
or if the user agent is to unload the
Document,
time
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 during the unloading document visibility change steps,
Queue a task that runs the following steps synchronously:
Set the hidden
attribute to true
.
If the user agent is to unload the
madedocument.visibilityStateattribute.ThiseventcanonlyberegisteredusingaddEventListeneronDocument,
set the document.visibilityState
attribute to unloaded
. This step is optional.
Fire a simple event willgetfirednamed onvisiblitychange
that bubbles, isn't cancelable, and has no default action,
at the firstchangeindocument.visibilityStateafterregistration;itwillnotgetfiredonregistration.Document.
4.4
IfaVendor-specific proprietary user agent extensions are discouraged. If such extensions are needed,
e.g., for experimental purposes, vendors MUST use the following extension mechanisms:
vendor-specific
If an extension to the visibilityState
attribute return value
is needed for an experimental visibility state, on getting the visibilityState attribute,
vendors mustMUST return a useDOMString
that uses the following convention:
constDOMString[VENDORPREFIX]_PAGE_[NAME]=[vendorprefix]-[name]"[vendorprefix]-[name]";
Where,
[VENDORPREFIX][vendorprefix]
is a [NAME][name]
is a
The Page Visibility API enables third party content on a non-capitalizednameweb page to determine the
visibility givenstate.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.
5
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.