Copyright
©
2012
2013
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
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/.
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 .
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>
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 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.
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 VisibilityStateDOMStringvisibilityState;// "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.
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
,
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.
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.
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.
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
now
visible
algorithm
before
running
the
step
to
fire
the
pageshow
event.
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 ,
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
,
Queue
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
.
This
step
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
.
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,
[vendorprefix]
is
a
non-capitalized
name
that
identifies
the
vendor,
[name]
is
a
non-capitalized
name
given
to
the
visibility
state,
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.
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.