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/.
ThisW3CpublishesaCandidateRecommendationtoindicatethatthedocument is believedtobestableandtoencourageimplementationby the LastCallWorkingDraftdevelopercommunity.
TheentrancecriteriaforthisdocumenttoentertheProposedRecommendationstageistohaveaminimum of twoindependentandinteroperableuseragentsthatimplementationall the PageVisibilityspecification.featuresofthisspecification,whichwillbedeterminedbypassingtheuseragenttestsdefinedinthetestsuitedevelopedbytheWorkingGroup.
Publication as a WorkingDraftCandidateRecommendation 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.
Implementersshouldbeawarethatthisdocumentisnotstable.Implementerswhoarenottakingpartinthediscussionsarelikelytofindthespecificationchangingoutfromundertheminincompatibleways.VendorsinterestedinimplementingthisdocumentbeforeiteventuallyreachestheCandidateRecommendationstageshouldjointheaforementionedmailinglistsandtakepartinthediscussions.Table of Contents
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, aweb developermustdesignthewebpagedevelopershavebeendesigningwebpages as if itistheyare 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 mailmessages 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 Javascriptscript shows a theoretical web based email client checking for new emailsmessages 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 emailsmessages
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>
The script will always check for emailsmessages 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.
The following script show the theoretical web based email client checking for new emailsmessages 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 emailsmessages
}
</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 construction "a Foo object", where Foo is actually an interface, is sometimes used instead of
the more accurate "an object implementing the interface Foo".
ThetermDOM4PageVisibility
4.1Introduction
Thissection is usedtorefertonon-normative.
ThisspecificationintroducesaninterfacethatprovidesWebapplicationswith the APIsetmadeavailablemeans to scriptsinWebapplications,anddoesnotnecessarilyimplyprogrammaticallydetermine the existencecurrentvisibility of anactualDocumentobjectorofanyotherNodeobjectsasdefinedintheDOMCorespecifications.ADOMattributeissaidtobegettingwhenitsvalueisbeingretrieved(suchasbyauthorscript),andissaidtobesettingwhenanewvalueisassignedtoit.Theterm"JavaScript"isusedtorefertoECMA-262,ratherthantheofficialtermECMAScript,sincethetermJavaScriptismorewidelyknown.4PageVisibility4.1IntroductionThissectionisnon-normativeThisspecificationintroducesaninterfacethatprovidesWebapplicationswiththemeanstoprogrammaticallydeterminethecurrentvisibilityofapageandbenotifiedapageandbenotified of visibility changes.
ThisOngetting,thehidden attribute returnsMUSTreturn true if the Document contained by the
top level browsing context (root window in the browser's viewport) [HTML5]
is not visible at all. ThisThe attribute returnsMUSTreturn false if the Document contained by the
top level browsing context
is at least partially visible on at least one screen.
To accommodate accessibility tools that are typically full screen but still show a
view of the page, when applicable, this attribute mayMAY return false when the User Agent
is not minimized but is fully obscured by other applications.
Note
As examples, ongetting, 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 OperatingSystemlockscreenUserAgent is shown.abouttounloadthepage.
The User Agent is minimizedandabouttotraverseto a previewsessionhistoryentry.
TheOperatingSystemlockscreen is shown.
Likewise, as examples, ongetting, 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.
To accommodate accessibility tools that are typically full screen but still show a
view of the page, when applicable, thisconstantmaynotbereturnedongetting,thevisibilityStateattributeMAYreturntheDOMStringvisible,insteadofhidden, when the User Agent
is not minimized but is fully obscured by other applications.
The User Agent is not minimized, but the page is on a background tab.
The Operating System lock screen is shown.
document.PAGE_VISIBLEThisvisible
Ongetting,thevisibilityState attribute mustMUST return document.PAGE_VISIBLEtheDOMStringvisible 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,apreviewoftheDocumentisvisible.To accommodate accessibility tools that are typically full screen but still show a
view of the page, when applicable, thisconstantmaybereturnedongetting,thevisibilityStateattributeMAYreturntheDOMStringvisible when the User Agent
is not minimized but is fully obscured by other applications.
The visibilitychangeUserAgentMUSTfirethevisiblitychangeeventattheDocumentwhentheUserAgentdeterminesthatthevisibilityoftheDocumentcontainedbythetoplevelbrowsingcontexthaschanged.
Ifavendor-specificVendor-specific proprietary user agent extensionsarediscouraged.Ifsuchextensionsareneeded,e.g.,forexperimentalpurposes,vendorsMUSTusethefollowingextensionmechanisms:
Ifan extension to the visibilityState attribute returnvalue
is needed for an experimental visibility state, ongettingthevisibilityStateattribute,
vendors mustuseMUSTreturnaDOMStringthatuses the following convention:
[VENDORPREFIX][vendorprefix] is a capitalizednon-capitalized name that identifies the vendor,
[NAME][name] is a capitalizednon-capitalized name given to the visibility state,
[vendorprefix]isanon-capitalizednamethatidentifiesand the vendor,[name]isabovenamesareinASCII.
5Privacy
ThePageVisibilityAPIenablesthirdpartycontenton a non-capitalizednamegivenwebpage to determine the
visibility state.5oftheDocumentcontainedbythetoplevelbrowsingcontextwithhigherprecisioncomparedtoexistingmechanisms,likefocusorblurevents.However,forpracticalconsiderations,theadditionalexposureisnotsubstantial.
HTML5, A.LeHors,etal.,Editors.IanHickson,Editor. World Wide Web Consortium, 7April2004.March2012. This version of the DocumentObjectModelLevel3CoreRecommendationHTML5 is http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407.availablefromhttp://www.w3.org/TR/html5/. The latest versionofDOMLevel3Coreeditor'sdraft is available at http://www.w3.org/TR/DOM-Level-3-Core.[ECMA-262]ECMAScriptLanguageSpecification,5thEdition.ECMAInternational,StandardECMA-262,December2009.ThisversionoftheECMAScriptLanguageisavailablefromhttp://www.ecma-international.org/publications/standards/Ecma-262.htm.http://dev.w3.org/html5/spec/.
HTML5WebIDL, IanHickson,CameronMcCormack, Editor. World Wide Web Consortium, May2011.April2012. This version of the HTML5WebIDLspecification is available from http://www.w3.org/TR/html5/.http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest editor'sdraftversionofWebIDL is available at http://dev.w3.org/html5/spec/.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.