Copyright © 2020 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 screen wake lock. Under the right conditions, and if allowed, the screen wake lock prevents the system from turning off a device's 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 Devices and Sensors Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification.
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 1 August 2017 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 15 September 2020 W3C Process Document.
This section is non-normative.
Modern operating systems achieve longer battery life by implementing aggressive power management, meaning that shortly after the lack of user activity, a host device may lower the screen brightness, turn the screen off and even let the CPU go into a deep power state, limiting power usage as much as possible.
Though this is great for prolonged battery life, it can sometime hinder some use cases such as scanning a barcode, reading an ebook, following a recipe, presenting to an audience, and so on. See also Wake Lock: Use cases.
A wake lock will generally prevent something from happening, but UAs (and the underlying OS) may time limit a wake lock given the battery status (wall power connected, discharging, low battery level), or even disallow wake locks in the case a power saving mode is activated.
This specification defines the following wake lock type:
In the API, the wake lock types are represented by the
enum values.
WakeLockType
Other specifications might define different wake lock types.
The Screen Wake Lock API defines a policy-controlled feature
identified by the string "screen-wake-lock"
. Its default
allowlist is ["self"]
.
The [PERMISSIONS] API provides a uniform way for websites to request permissions from users and query which permissions they have.
A user agent can deny a wake lock of a
particular wake lock type for a particular Document
by any
implementation-specific reason, such as platform setting or user
preference.
It is RECOMMENDED that a user agent show some form of unobtrusive notification that informs the user when a wake lock is active, as well as provides the user with the means to block the ongoing operation, or simply dismiss the notification.
"screen-wake-lock"
powerful feature
The "screen-wake-lock"
powerful feature enables the
capability defined by this specification.
To block a permission, run these steps:
PermissionDescriptor
.
denied
".
name
member.
[[ActiveLocks]]
:
To obtain permission for wake lock type name, run
these steps in parallel. This async algorithm returns either
"granted
" or "denied
".
PermissionDescriptor
.
name
member to
"screen-wake-lock
".
denied
".
state
.
prompt
", return state.
denied
".
The term platform wake lock refers to platform interfaces with which the user agent interacts to query state and acquire and release a wake lock.
A platform wake lock can be defined by the underlying platform (e.g. in a native wake lock framework) or by the user agent, if it has direct hardware control.
Each platform wake lock (one per wake lock type) has an associated state record per responsible document with the following internal slots:
Internal slot | Initial value | Description (non-normative) |
---|---|---|
[[ActiveLocks]] | The empty list. |
A list of objects, representing
active wake locks associated with the responsible document.
|
WakeLock
interface
The
interface allows a document to acquire a screen wake
lock.
WakeLock
WebIDL[SecureContext, Exposed=(Window)] interfaceWakeLock
{ Promise<WakeLockSentinel
>request
(WakeLockType
type); };
request()
method
The request
()
method, when invoked, MUST run the
following steps. The method takes one argument, the
type:
WakeLockType
screen-wake-lock
", return a promise rejected
with a "NotAllowedError
" DOMException
.
NotAllowedError
" DOMException
.
null
,
return a promise rejected with "NotAllowedError
"
DOMException
.
NotAllowedError
" DOMException
.
hidden
, return a promise rejected with
"NotAllowedError
" DOMException
.
hidden
.
screen-wake-lock
":
denied
", then reject
promise with a "NotAllowedError
" DOMException
, and
abort these steps.
WakeLockSentinel
object with its type
attribute set to
type.
screen
".
NotAllowedError
"
DOMException
.
WakeLockSentinel
interface
WebIDL[SecureContext, Exposed=(Window)] interfaceWakeLockSentinel
: EventTarget { readonly attribute booleanreleased
; readonly attributeWakeLockType
type
; Promise<undefined>release
(); attribute EventHandleronrelease
; };
A
object provides a handle to a platform wake
lock, and it holds on to it until it is either manually released or
until the underlying platform wake lock is released. Its
existence keeps a platform wake lock for a given wake lock
type active, and releasing all WakeLockSentinel
instances of a
given wake lock type will cause the underlying platform wake
lock to be released.
WakeLockSentinel
instances are created with the following
internal
slots:
WakeLockSentinel
Internal slot | Initial value | Description (non-normative) |
---|---|---|
[[Released]] |
false
|
Whether the given has been released.
|
released
attribute
The
attribute's getter returns the
value of the released
[[Released]]
internal slot.
type
attribute
The
attribute corresponds to the
type
's wake lock type.
WakeLockSentinel
release()
method
The release
()
method, when invoked, MUST run the
following steps:
[[Released]]
internal slot is true
, return
a promise resolved with undefined
.
type
attribute.
onrelease
attribute
The
attribute is an event
handler whose corresponding event handler event type is
onrelease
release
.
It is used to notify scripts that a given
object's handle has been released, either due to the
WakeLockSentinel
release
()
method being called or because the
wake lock was released by the user agent.
WakeLockType
enum
For the purpose of wake lock type description, this specification defines the following enumeration to represent wake lock types:
WebIDLenumWakeLockType
{ "screen
" };
screen
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. A possible return value of the request to the underlying operating system is not checked. In other words, user agents MUST treat wake lock acquisition as advisory-only.
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.
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 switched off by the user until it is switched on again.
A user agent may release a wake lock at any time it:
When the user agent determines that a responsible document of the current settings object is no longer fully active, it must run these steps:
[[ActiveLocks]]
:
screen
".
When the user agent determines that the visibility state of the responsible document of the current settings object changes, it must run these steps:
"visible"
, abort
these steps.
[[ActiveLocks]]
:
screen
".
To acquire a wake lock for a given lock and type, run these steps in parallel:
false
.
[[ActiveLocks]]
.
To release a wake lock for a given lock and type, run these steps in parallel:
[[ActiveLocks]]
does not contain lock, abort
these steps.
[[ActiveLocks]]
.
[[ActiveLocks]]
of all the platform
wake lock's state records are all empty, then run the
following steps in parallel:
true
if the
operation succeeded, or else false
.
true
and type is "screen"
run the
following:
[[Released]]
internal slot to true
.
release
" at lock.
Wake locks can cause various device components such as display or CPU to operate at higher power levels than they otherwise would. This can lead to undesirable effects such as faster than normal battery charge depletion. This 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 MAY ignore requests for screen wake lock if, for example, the battery capacity is low, or the user has put their device in a power-saving mode.
This section is non-normative.
function tryKeepScreenAlive(minutes) {
navigator.wakeLock.request("screen").then(lock => {
setTimeout(() => lock.release(), minutes * 60 * 1000);
});
}
tryKeepScreenAlive(10);
This example allows the user to request a screen wake lock by clicking on a checkbox, but updates the checkbox checked state in case the wake lock state changes:
const checkbox = document.createElement("input");
checkbox.setAttribute("type", "checkbox");
document.body.appendChild(checkbox);
const sentinel = await navigator.wakeLock.request("screen");
checkbox.checked = !sentinel.released;
sentinel.onrelease = () => checkbox.checked = !sentinel.released;
In this example, two different wake lock requests are created and released independently:
let lock1 = await navigator.wakeLock.request("screen");
let lock2 = await navigator.wakeLock.request("screen");
lock1.release();
lock2.release();
Document's hidden
attribute,
and visibility
state are defined in [PAGE-VISIBILITY].
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, MUST NOT, and RECOMMENDED in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.
WebIDL[SecureContext] partial interface Navigator { [SameObject] readonly attributeWakeLock
wakeLock
; }; [SecureContext, Exposed=(Window)] interfaceWakeLock
{ Promise<WakeLockSentinel
>request
(WakeLockType
type); }; [SecureContext, Exposed=(Window)] interfaceWakeLockSentinel
: EventTarget { readonly attribute booleanreleased
; readonly attributeWakeLockType
type
; Promise<undefined>release
(); attribute EventHandleronrelease
; }; enumWakeLockType
{ "screen
" };
This section is non-normative.
We would like to offer our sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux, Domenic Denicola, Thomas Steiner, Raphael Kubo da Costa for their contributions to this work.
This section is non-normative.
This section documents the changes since previous publications.
WakeLock.request()
to deal with hidden documents.
ScreenWakeLock
constructable.