Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document specifies an API that allows web applications to request a wake lock. A wake lock prevents some aspect of the device from entering a power-saving state (e.g., preventing the system from turning off the screen).
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 https://www.w3.org/TR/.
Implementors need to be aware that this specification is extremely unstable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.
This document was published by the Device APIs Working Group as a Working Draft. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-device-apis@w3.org (subscribe, archives).
Please see the Working Group's implementation report.
Publication as a Working Draft 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 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 document is governed by the 1 March 2017 W3C Process Document.
A wake lock prevents some aspect of the device or operating system from entering a power-saving state.
This specification defines two wake lock types:
The Wake Lock API MUST be available only in secure context.
A user agent MAY deny wake lock of a particular type or all types for a particular Document, and MUST do so in cases explicitly defined by this specification.
A user agent MAY check user settings or request user permission in order to decide whether it will deny wake lock of a particular type for a particular Document.
The wake lock feature is a policy-controlled feature
with feature name wake-lock
and default
allowlist ["self"]
.
If Document's feature policy disables the wake lock feature, the user agent MUST deny wake lock.
The default allowlist of ["self"]
allows wake
lock usage in same-origin nested frames but prevents third-party
content from using wake locks.
Third-party usage can be selectively enabled by adding
allow="wake-lock"
attribute to the frame container
element:
<iframe src="https://third-party.com" allow="wake-lock"/></iframe>
Alternatively, the wake lock feature can be disabled completely by specifying the feature policy in a HTTP response header:
Feature-Policy: {"wake-lock": []}
See [FEATURE-POLICY] for more details.
WakeLockType
enum
For the purpose of wake lock type description, this specification defines the following enumeration:
enum WakeLockType
{
"screen",
"system"
};
screen
system
WakeLock
interface
The WakeLock
interface allows the page to request wake locks of
a particular type, to determine the current wake lock state and to
receive notifications when the wake lock state is changed.
[SecureContext,
Exposed=Window]
interface WakeLock
: EventTarget {
readonly attribute WakeLockType
type
;
readonly attribute boolean active
;
attribute EventHandler onactivechange
;
WakeLockRequest
createRequest();
};
type
WakeLock
object.
active
onactivechange
activechange
. Fired when current wake lock
status indicated by the active
attribute changes.
To create and
initialize a WakeLock
object of type type, the
following steps MUST be performed:
WakeLock
object in the Realm of this
Navigator
object and let wakeLock be that object.
type
attribute of wakeLock to
type.
active
attribute of
wakeLock to true
, otherwise to
false
.
Internally, each WakeLock
object contains request
counter which is initially set to zero. Each time the
createRequest()
method is called on the object, the request
counter is increased by one.
A WakeLock
object has an outstanding wake lock
request when its request counter is greater than zero.
When the createRequest()
method is invoked, the following
steps MUST be performed:
WakeLockRequest
object in the Realm of
this WakeLock
object and let wakeLockRequest be that
object.
WakeLock
object.
WakeLockRequest
interface
[SecureContext,
Exposed=Window]
interface WakeLockRequest
{
void cancel();
};
Each WakeLockRequest
object has an implicit owner wake lock
reference to the WakeLock
object through which this object
was created. When the cancel()
method is invoked, the
following steps MUST be performed:
cancel()
method has already been invoked on this
object, abort these steps.
This section applies to each wake lock type equally and independently, unless a particular wake lock type is explicitly mentioned.
The user agent acquires the wake lock by requesting the underlying operating system to apply the lock. The lock is considered acquired only when the request to the operating system succeeds.
Conversely, the user agent releases the wake lock by requesting the underlying operating system to no longer apply the wake lock. The lock is considered released only when the request to the operating system succeeds.
When the user agent releases wake
lock of type screen
it MUST
reset the platform-specific inactivity timer after which the screen is
actually turned off.
A Document is requesting the wake lock of type
type if and only if the following procedure returns
true
:
document.defaultView
.
null
, return
false
and abort these steps.
Navigator
object returned by
window.navigator
.
false
and abort these steps.
screen
"
and document is hidden
, return false
and
abort these steps.
WakeLock
object, has an outstanding wake lock request, return
true
, otherwise return false
.
The wake lock is applicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge).
The screen wake lock MUST NOT be applicable after the screen is manually swiched off by the user until it is switched on again. Manually switching off the screen MUST NOT affect the applicability of the system wake lock.
The user agent MUST acquire the wake lock of type type when all of the following conditions become true:
The user agent MUST release the wake lock when any of the conditions above become false.
Whenever user agent acquires or releases a wake lock, the
user agent MUST perform the following steps for each
WakeLock
object:
WakeLock
object's type
attribute is not equal to type, abort these steps.
WakeLock
object's
active
attribute and fires an
event named activechange
at the WakeLock
object.
In the task described above, the WakeLock
objects's
active
attribute MUST be set to true
if the
wake lock has been acquired or to false
if the wake lock
has been released.
Application of a wake lock causes various device components such as display or CPU to operate at higher power levels than they otherwise would. This can lead to undesirable and potentially dangerous effects such as excessive heating and faster than normal battery charge depletion. The latter is particularly relevant to mobile devices which may not have a stationary power source readily available. Complete battery depletion at an unexpected time can lead to inability of the user to make or receive calls and use network services, including the emergency call service. Implementations should consider preventing wake lock application if they determine that the remaining battery capacity is low.
The ability to observe the global state of a wake lock can create a
communication channel between two otherwise isolated documents. One document can request wake lock which
changes the global wake lock state, and another document can observe
this change by subscribing to events in WakeLock
.
When the user agent does not acquire wake lock even though a browsing context has requested it, this can be observed by the browsing context and can possibly disclose sensitive information about the state of the device such as that battery level is low.
This section is non-normative.
This example acquires a screen wake lock and releases it after a while:
navigator.getWakeLock("screen").then(function(wakeLock) {
var request = wakeLock.createRequest();
setTimeout(function() {
request.cancel();
}, 1000);
});
This example requests a screen wake lock and listens to wake lock state changes:
var request;
navigator.getWakeLock("screen").then(function(wakeLock) {
request = wakeLock.createRequest();
document.getElementById("wakeLockActive").innerHTML = wakeLock.active;
wakeLock.onactivechange = function() {
document.getElementById("wakeLockActive").innerHTML = wakeLock.active;
};
});
In this example, two screen wake lock requests are created and cancelled independently:
var request1;
navigator.getWakeLock("screen").then(function(wakeLock) {
request1 = wakeLock.createRequest();
});
// ...
var request2;
navigator.getWakeLock("screen").then(function(wakeLock) {
request2 = wakeLock.createRequest();
});
// ...
request1.cancel();
request2.cancel();
The following concepts and interfaces are defined in [HTML]:
Navigator
The following concepts and interfaces are defined in [WHATWG-DOM]:
The following concepts and interfaces are defined in [WEBIDL]:
The following concepts are defined in [PROMISES-GUIDE]:
The following concepts and interfaces are defined in [ECMASCRIPT]:
The following concepts and interfaces are defined in [PAGE-VISIBILITY]:
hidden
attribute
The following concepts and interfaces are defined in [FEATURE-POLICY]:
This section is non-normative.
The use cases and requirements are documented in [WAKE-LOCK-USE-CASES].
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and MUST NOT are to be interpreted as described in [RFC2119].
This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.
The user agent MUST implement the APIs defined in this specification in a manner that conforms to the ECMAScript Bindings defined in [WEBIDL].
This section is non-normative.
We would like to offer our sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux (via the HTML5Apps project) for their contributions to this work.