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).
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.
//request to keep the display awake when the recipe is showing: screen.keepAwake = true; //stop keeping the display awake: screen.keepAwake = false;
A wake lock prevents some aspect of the device or operating system from entering a power-saving state.
This specification deals specifically with the screen wake lock which prevents the screen(s) of the device from entering a power-saving state.
This specification extends Screen interface defined by
[[!CSSOM-VIEW]] to allow document scripts to inform the browser that
they prefer to keep the device screen awake:
true to
request wake lock or to false to
cancel wake lock request.
Each browsing context has a request flag for the
wake lock, represented by its screen.keepAwake
attribute. The request flag is set to false when the
browsing context is created or its active document is
changed. Request flags are used by user agent to track if a
particular document is requesting the lock (for the purpose of
acquiring or releasing the
corresponding operating system lock).
A document requests wake lock by setting browsing context's lock request flag. This means that the document indicates to the user agent a preference that the underlying operating system apply wake lock, i.e. keep the screen on.
A document can successfully request wake lock regardless of whether the actual lock can be applied by the user agent and/or the underlying operating system at the time when the request is made.
Conversely, a document cancels wake lock request by resetting its browsing context's lock request flag . This means that the document indicates to the user agent that it no longer prefers that the underlying system apply the wake lock.
Setting or resetting a lock request flag merely indicates a preference of the document to have the wake lock applied. Requesting the lock or cancelling wake lock request does not entail synchronous acquisition or release of the corresponding operating system lock, and can only result in an error when the document is explicitly prohibited form executing those operations by some security mechanism.
No document "owns" the operating system lock and the state of operating system lock does not affect the state of the lock request flag for any document's browsing context.
Instead, user agent is responsible for mapping the state of request flags for all browsing contexts to the state the operating system lock.
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, user agent releases 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.
A browsing context is relevant to the wake lock if:
visibilityState attribute has value of visible
as defined by [[!PAGE-VISIBILITY]].
The wake lock is applicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge and wake locking is not disabled by a user setting).
User agent MUST acquire the wake lock when all of the following conditions become true:
User agent MUST release the wake lock when any of the conditions above become false.
From the user's perspective, a document which has requested the wake lock will no longer cause the lock to be applied if one of the following happens:
Should the tab and/or browser window once again come to foreground, the lock will be applied again if it is still requested and the state of the operating system permits its application.
The lock request and management mechanism presented in this document can be extended to support additional types of locks by adding new lock request flags to appropriate interface objects. E.g. a "system" wake lock could be introduced which would prevent the device's cpu, radio(s), and other system services from entering a power-saving state while allowing the screen to switch off.
The following concepts and interfaces are defined in [[!HTML]]:
The following concepts and interfaces are defined in [[!PAGE-VISIBILITY]]:
The use cases and requirements are documented in [[WAKE-LOCK-USE-CASES]].
This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.
A user agent MUST implement the APIs defined in this specification in a manner that conforms to the ECMAScript Bindings defined in [[!WEBIDL]].
We would like to offer my sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux (via the HTML5Apps project) for their contributions to this work.