Abstract

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

Status of This Document

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 http://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 Device APIs Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All comments are welcome.

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 5 February 2004 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 1 September 2015 W3C Process Document.

1. Examples

This section is non-normative.

Example 1
//request to keep the display awake when the recipe is showing:
screen.keepAwake = true;

//stop keeping the display awake:
screen.keepAwake = false;

2. Wake Locks

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.

3. Extension to Screen interface

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:

partial interface Screen {
    attribute boolean keepAwake;
};

The attribute keepAwake reflects the state of the wake lock request flag. Document script can set this attribute to true to request wake lock or to false to cancel wake lock request.

4. Requesting Wake Locks

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

Note

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 from 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, the user agent is responsible for mapping the state of request flags for all browsing contexts to the state the operating system lock.

5. Managing Wake Locks

The 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, the 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:

  1. Its active document is visible, i.e. its visibilityState attribute has value of visible as defined by [PAGE-VISIBILITY].
  2. The browsing context's wake lock request flag is set.
  3. The browsing context is either a top-level browsing context or its active document's origin is the same as that of the active document of its top-level browsing context.
Note

The same-origin requirement prevents unauthorized nested third-party content from requesting a wake lock on behalf of the top-level page.

An alternative approach could be requiring a permission as defined in [ PERMISSIONS] which would effectively delegate decisions about wake lock in nested browsing contexts to the user agent. The downside is that permission inheritance model is currently non-portable between implementations and sometimes inconsistent even within the same implementation. For more details see e.g. this Chromium design document.

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

The user agent MUST acquire the wake lock when all of the following conditions become true:

  1. The wake lock is applicable.
  2. There is at least one browsing context that is relevant to the wake lock.

The user agent MUST release the wake lock when any of the conditions above become false.

Note

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:

  • Browser tab or window is closed.
  • Switching from one tab to another.
  • Browser is minimized.
  • Navigating to a different page or reloading a page.

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.

6. Additional lock types

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.

7. Security and privacy considerations

Application of a wake lock causes various device components such as display or CPU to operate at higher power levels than they otherwise would. This can lead to undesirable and potentially dangerous effects such as excessive heating and faster than normal battery charge depletion. The latter 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 should consider preventing wake lock application if they determine that the remaining battery capacity is low.

8. Dependencies

The following concepts and interfaces are defined in [HTML]:

The following concepts and interfaces are defined in [ PAGE-VISIBILITY]:

9. Use cases

This section is non-normative.

The use cases and requirements are documented in [ WAKE-LOCK-USE-CASES].

10. Conformance

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 word MUST is to be interpreted as described in [RFC2119].

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

The user agent MUST implement the APIs defined in this specification in a manner that conforms to the ECMAScript Bindings defined in [WEBIDL].

A. Acknowledgments

This section is non-normative.

We would like to offer our sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux (via the HTML5Apps project) for their contributions to this work.

B. References

B.1 Normative references

[CSSOM-VIEW]
Simon Pieters. W3C. CSSOM View Module. 17 March 2016. W3C Working Draft. URL: https://www.w3.org/TR/cssom-view-1/
[HTML]
Ian Hickson. WHATWG. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[PAGE-VISIBILITY]
Jatinder Mann; Arvind Jain. W3C. Page Visibility (Second Edition). 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/
[PERMISSIONS]
Mounir Lamouri; Marcos Caceres. W3C. The Permissions API. 7 April 2015. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/WebIDL-1/

B.2 Informative references

[WAKE-LOCK-USE-CASES]
Marcos Caceres; Natasha Rooney; Dominique Hazaël-Massieux. W3C. Wake Lock: Use cases. 14 August 2014. W3C Note. URL: https://www.w3.org/TR/wake-lock-use-cases/