Screen Wake Lock API

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.

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

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.

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

The WakeLock interface allows a document to acquire a screen wake lock .

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

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

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

WebIDL




enum


WakeLockType


{

"


screen


"

};

screen

Screen wake lock type.

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 can release 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.

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.

A user agent MAY 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.

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.