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.
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 shouldsubscribe to the repository on GitHub and take part in the discussions.
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 followingwake lock type:
In the API, the [=wake lock types=] are represented by the {{WakeLockType}} enum values.
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 [=policy-controlled feature/default allowlist=] is `'self'`.
The [=policy-controlled feature/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="screen-wake-lock"` attribute to the frame container element:
<iframe src="https://third-party.com" allow="screen-wake-lock"/></iframe>
Alternatively, the Screen Wake Lock API can be disabled completely by specifying the permissions policy in a HTTP response header:
Permissions-Policy: screen-wake-lock=()
See [[[PERMISSIONS-POLICY]]] for more details.
The [[PERMISSIONS]] API provides a uniform way for websites to request permissions from users and query which permissions they have.
Auser agent candeny a wake lock of a particularwake 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 [=screen wake lock permission revocation algorithm|block=] the ongoing operation, or simply dismiss the notification.
The `"screen-wake-lock"`powerful feature enables the capability defined by this specification.
The `"screen-wake-lock"`powerful feature defines a [=powerful feature/permission revocation algorithm=]. To invoke theScreen Wake Lock permission revocation algorithm, run these steps:
Thetask source for thetasks mentioned in this specification is thescreen wake lock task source.
The termplatform wake lock refers to platform interfaces with which the user agent interacts to query state and acquire and release a wake lock.
Aplatform 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.
| Internal slot | Initial value | Description |
|---|---|---|
| [[\ActiveLocks]] | Anordered map mappingwake lock types to emptylists. | Anordered map ofwake lock types to alist of {{WakeLockSentinel}} objects associated with this {{Document}}. |
[SecureContext] partial interface Navigator { [SameObject] readonly attribute WakeLock wakeLock; };The {{WakeLock}} interface allows a document to acquire a [=screen wake lock=].
[SecureContext, Exposed=(Window)] interface WakeLock { Promise<WakeLockSentinel> request(optional WakeLockType type = "screen"); }; Therequest(|type:WakeLockType|) method steps are:
[SecureContext, Exposed=(Window)] interface WakeLockSentinel : EventTarget { readonly attribute boolean released; readonly attribute WakeLockType type; Promise<undefined> release(); attribute EventHandler onrelease; };A {{WakeLockSentinel}} object provides a handle to aplatform wake lock, and it holds on to it until it is either manually released or until the underlyingplatform wake lock is released. Its existence keeps aplatform wake lock for a givenwake lock type active, and releasing all {{WakeLockSentinel}} instances of a givenwake lock type will cause the underlyingplatform wake lock to be released.
Seeauto-releasing wake locks,handling document loss of full activity andhandling document loss of visibility for circumstances under which a given wake lock may be released by theuser agent.{{WakeLockSentinel}} instances are created with the followinginternal slots:
| Internal slot | Initial value | Description (non-normative) |
|---|---|---|
| [[\Released]] | `false` | Whether the given {{WakeLockSentinel}} has been released. |
The {{WakeLockSentinel/released}} getter steps are to return [=this=].{{WakeLockSentinel/[[Released]]}}.
Once a {{WakeLockSentinel}} is released, {{WakeLockSentinel/released}} becomes `true`, and the value never changes again.The {{WakeLockSentinel/type}} getter steps are to return [=this=]'swake lock type.
The {{WakeLockSentinel/release()}} method steps are:
The {{WakeLockSentinel/onrelease}} attribute is anevent handler IDL attribute for the "onrelease"event handler, whoseevent handler event type is "release".
It is used to notify scripts that a given {{WakeLockSentinel}} object's handle has been released, either due to the {{WakeLockSentinel/release()}} method being called or because the wake lock was released by theuser agent.
A {{WakeLockSentinel}} object's handle being released does not necessarily mean theplatform wake lock for a givenwake lock type was released. That depends on theplatform wake lock's {{Document/[[ActiveLocks]]}} internal slot. Seerelease a wake lock. [[[#onrelease-example]]] contains an example of how to use the {{WakeLockSentinel/onrelease}} event handler. While a {{WakeLockSentinel}} object has one or more event listeners registered for "release", and the {{WakeLockSentinel}} object hasn't already been released, there MUST be a strong reference from the {{Window}} object that the {{WakeLockSentinel}} object's constructor was invoked from to the {{WakeLockSentinel}} object itself.
While there is a task queued by an {{WakeLockSentinel}} object on thescreen wake lock task source, there MUST be a strong reference from the {{Window}} object that the {{WakeLockSentinel}} object's constructor was invoked from to that {{WakeLockSentinel}} object.
For the purpose of wake lock type description, this specification defines the following enumeration to represent [=wake lock types=]:
enum WakeLockType { "screen" };This section applies to eachwake lock type equally and independently, unless a particularwake lock type is explicitly mentioned.
Theuser agentacquires 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 asadvisory-only.
Conversely, theuser agentreleases 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 isapplicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge).
Thescreen wake lock MUST NOT beapplicable after the screen is manually switched off by the user until it is switched on again.
Whether the wake lock is applicable is a transient condition, e.g. when the battery charge is low but then the battery is recharged. So like the visibility requirement, this is part of automatic wake lock management and not part of the decision process whether to allow or deny the wake lock.A user agent mayrelease a wake lock at any time. For example, when:
When a {{Document}} |document:Document| becomes no longer [=Document/fully active=], the user agent must run these steps:
This specification defines the following [=page visibility change steps=] with [=Document/visibility state=] |state| and |document:Document|:
Toacquire a wake lock for a given |type:WakeLockType|, run these steps:
Torelease a wake lock for a given |document:Document|, |lock:WakeLockSentinel|, and |type:WakeLockType|, run these steps:
release" at |lock|.Screen wake locks can cause various device components - particularly the display - to operate at higher power levels than they otherwise would. This can lead to undesirable effects, such as preventing the device from automatically locking itself and faster battery depletion. Faster battery depletion is of particular concern for mobile devices, which often don't 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.
It is RECOMMENDED that a user agent provide some UI or indicator that allows the user to know when a screen wake lock is active. Providing such a UI could help end users to identify if a particular web application is having a negative energy impact on the device, and allow them to take action if so desired.
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();This specification defines conformance criteria for a single product: auser agent that implements the interfaces that it contains.
We would like to offer our sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux, Domenic Denicola, Thomas Steiner, Anne van Kesteren for their contributions to this work.
This section documents the changes since previous publications.
WakeLock.request() to deal with hidden documents.WakeLockSentinel.released.