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 should subscribe to the repository on GitHub and take part in the discussions.

Introduction

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.

Wake Locks

This specification defines the following wake lock type:

  1. A screen wake lock prevents the screen from turning off. Only visible documents can acquire the screen wake lock.

In the API, the [=wake lock types=] are represented by the {{WakeLockType}} enum values.

Other specifications might define different wake lock types.

Policy control

The Screen Wake Lock API defines a [=policy-controlled feature=] identified by the string `"screen-wake-lock"`. Its [=default allowlist=] is `["self"]`.

Permissions and user prompts

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 [=screen wake lock permission revocation algorithm|block=] the ongoing operation, or simply dismiss the notification.

The `"screen-wake-lock"` powerful feature

The `"screen-wake-lock"` powerful feature enables the capability defined by this specification.

Permission algorithms

The `"screen-wake-lock"` powerful feature defines a permission revocation algorithm. To invoke the Screen Wake Lock permission revocation algorithm, run these steps:

  1. Let |document:Document| be the [=current settings object=]'s [=associated Document=].
  2. Let |lockList| be |document|.{{[[ActiveLocks]]}}["`screen`"].
  3. [=list/For each=] |lock:WakeLockSentinel| in |lockList|:
    1. Run release a wake lock with |document|, |lock|, and {{WakeLockType/"screen"}}.

To obtain permission for wake lock type |name|, run the following steps. This algorithm returns either {{PermissionState/"granted"}} or {{PermissionState/"denied"}}.

  1. Let |state:PermissionState| be permission state of the `"screen-wake-lock"` {{PermissionName}}.
  2. If |state| is not {{PermissionState/"prompt"}}, return |state|.
  3. If the current global object does not have [=transient activation=], return {{PermissionState/"denied"}}.
  4. Otherwise, return the result of requesting permission to use the `"screen-wake-lock"` {{PermissionName}}.

Concepts

The task source for the tasks mentioned in this specification is the screen wake lock task source.

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.

Extensions to the `Document` interface

Internal slots

Internal slot Initial value Description
[[\ActiveLocks]] An ordered map mapping wake lock types to empty lists. An ordered map of wake lock types to a list of {{WakeLockSentinel}} objects associated with this {{Document}}.

Extensions to the `Navigator` interface

        [SecureContext]
        partial interface Navigator {
          [SameObject] readonly attribute WakeLock wakeLock;
        };
      

The WakeLock interface

The {{WakeLock}} interface allows a document to acquire a [=screen wake lock=].

        [SecureContext, Exposed=(Window)]
        interface WakeLock {
          Promise<WakeLockSentinel> request(optional WakeLockType type = "screen");
        };
      

The request() method

The {{WakeLock/request()}} method, when invoked, MUST run the following steps. The method takes one argument, the {{WakeLockType}} |type:WakeLockType|:

  1. Let |document:Document| be [=this=]'s [=relevant settings object=]'s [=associated Document=].
  2. If |document| is not [=allowed to use=] the [=policy-controlled feature=] named "`screen-wake-lock`", return [=a promise rejected with=] a {{"NotAllowedError"}} {{DOMException}}.
  3. If the user agent denies the wake lock of this |type| for |document|, return [=a promise rejected with=] a {{"NotAllowedError"}} {{DOMException}}.
  4. If the |document|'s [=Document/browsing context=] is `null`, return [=a promise rejected with=] {{"NotAllowedError"}} {{DOMException}}.
  5. If |document| is not [=Document/fully active=], return [=a promise rejected with=] with a {{"NotAllowedError"}} {{DOMException}}.
  6. If the steps to determine the visibility state return `hidden`, return [=a promise rejected with=] {{"NotAllowedError"}} {{DOMException}}.
  7. Let |promise:Promise| be [=a new promise=].
  8. Run the following steps in parallel:
    1. Let |state:PermissionState| be the result of invoking obtain permission with "`screen-wake-lock`".
    2. If |state| is {{PermissionState/"denied"}}, then:
      1. Queue a global task on the screen wake lock task source given |document|'s relevant global object to reject |promise| with a {{"NotAllowedError"}} {{DOMException}}.
      2. Abort these steps.
    3. Queue a global task on the screen wake lock task source given |document|'s relevant global object to run these steps:
      1. If the steps to determine the visibility state return `hidden`, then:
        1. Reject |promise| with a {{"NotAllowedError"}} {{DOMException}}.
        2. Abort these steps.
      2. If |document|.{{[[ActiveLocks]]}}["`screen`"] [=list/is empty=], then invoke the following steps in parallel:
        1. Invoke acquire a wake lock with {{WakeLockType/"screen"}}.
      3. Let |lock:WakeLockSentinel| be a new {{WakeLockSentinel}} object with its {{WakeLockSentinel/type}} attribute set to |type|.
      4. [=List/Append=] |lock| to |document|.{{[[ActiveLocks]]}}["`screen`"].
      5. Resolve |promise| with |lock|.
  9. Return |promise|.

The WakeLockSentinel interface

        [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 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.

Internal slots

{{WakeLockSentinel}} instances are created with the following internal slots:

Internal slot Initial value Description (non-normative)
[[\Released]] `false` Whether the given {{WakeLockSentinel}} has been released.

The released attribute

The {{WakeLockSentinel/released}} attribute's getter returns the value of the {{[[Released]]}} internal slot.

The type attribute

The {{WakeLockSentinel/type}} attribute corresponds to the {{WakeLockSentinel}}'s wake lock type.

The release() method

The {{WakeLockSentinel/release()}} method, when invoked, MUST run the following steps:

  1. If this's {{[[Released]]}} is `false`, then run release a wake lock with |lock:WakeLockSentinel| set to this and |type:WakeLockType| set to the value of this's {{WakeLockSentinel/type}} attribute.
  2. Return a promise resolved with `undefined`.

The onrelease attribute

The {{WakeLockSentinel/onrelease}} attribute is an event handler whose corresponding event 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 the user agent.

The WakeLockType enum

For the purpose of wake lock type description, this specification defines the following enumeration to represent [=wake lock types=]:

        enum WakeLockType { "screen" };
      
screen
Screen wake lock type.

Managing Wake Locks

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.

Auto-releasing wake locks

A user agent may release a wake lock at any time. For example, when:

Handling document loss of full activity

When a {{Document}} |document:Document| becomes no longer [=Document/fully active=], the user agent must run these steps:

  1. [=list/For each=] |lock:WakeLockSentinel| in |document|.{{[[ActiveLocks]]}}["`screen`"]:
    1. Run release a wake lock with |document|, |lock|, and {{WakeLockType/"screen"}}.

Handling document loss of visibility

When the user agent determines that the [=Document/visibility state=] of a {{Document}} |document:Document| of a top-level browsing context has become `hidden`, the user agent MUST run the following steps after the now hidden algorithm:

  1. [=list/For each=] |lock:WakeLockSentinel| in |document|.{{[[ActiveLocks]]}}["`screen`"]:
    1. Run release a wake lock with |document|, |lock|, and {{WakeLockType/"screen"}}.

Acquire wake lock algorithm

To acquire a wake lock for a given |type:WakeLockType|, run these steps:

  1. If the wake lock for type |type| is not applicable, abort these steps.
  2. Ask the underlying operating system to acquire the wake lock of type |type|.

Release wake lock algorithm

To release a wake lock for a given |document:Document|, |lock:WakeLockSentinel|, and |type:WakeLockType|, run these steps:

  1. If |document|.{{[[ActiveLocks]]}}[|type|] does not contain |lock|, abort these steps.
  2. Remove |lock| from |document|.{{[[ActiveLocks]]}}[|type|].
  3. If |document|.{{[[ActiveLocks]]}}[|type|] [=list/is empty=], then run the following steps in parallel:
    1. Ask the underlying operating system to release the wake lock of type |type| and let |success:boolean| be `true` if the operation succeeded, or else `false`.
    2. If |success| is `true` and |type| is `"screen"` run the following:
      1. Reset the platform-specific inactivity timer after which the screen is actually turned off.
  4. Set |lock|'s {{[[Released]]}} to `true`.
  5. Fire an event named "`release`" at |lock|.

Security and privacy considerations

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.

Examples

        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();
      

Dependencies

The following is defined in [[PAGE-VISIBILITY]]: now hidden algorithm.

This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.

Acknowledgments

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.

Changes

This section documents the changes since previous publications.

Changes since the 14 December 2017 CR