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 https://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. Wake Locks

A wake lock prevents some aspect of the device or operating system from entering a power-saving state.

This specification defines two wake lock types:

  1. Screen wake lock which prevents device's screen from turning off so that the user can still see the information displayed on the screen.
  2. System wake lock which prevents device's CPU from entering a standby mode so that the programs can continue running.
Note
One type of wake lock can imply the effects of another: for example, screen wake lock logically implies that the program which displays information on the screen continues running, as if the system wake lock were also applied. But to avoid dependence on such implementation details which may not always be true, this specification treats all types of wake locks as independent.

A user agent MAY deny wake lock of a particular type or all types on per-browsing context basis, and MUST do so in cases explicitly defined by this specification.

A user agent MAY check user settings or request user permission in order to decide whether it will deny wake lock of a particular type for a particular browsing context.

If the browsing context is not a top-level browsing context and its active document's origin is not the same as that of the active document of its top-level browsing context, the user agent MUST deny wake lock.

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.

2. The WakeLockType enum

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

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

3. The Navigator interface 

partial interface Navigator {
    Promise<WakeLock> getWakeLock(WakeLockType type);
};

For each Navigator object, there is a wake lock map which contains a single wake lock promise for each wake lock type. Each wake lock promise in the wake lock map is a Promise object which holds a WakeLock. All wake lock promises are initially set to null.

The getWakeLock() method, when invoked with an argument type, MUST run the following steps:

  1. Let wakeLockPromise be the wake lock promise associated with type in this Navigator's wake lock map.
  2. If wakeLockPromise is not null, return wakeLockPromise and abort these steps.
  3. Otherwise, set wakeLockPromise to a newly created Promise created in the Realm of this Navigator object.
  4. If the user agent does not support the wake lock type denoted by type, or has otherwise determined it will deny wake lock of this type for this browsing context, reject wakeLockPromise, return wakeLockPromise and abort these steps.
  5. If the user agent cannot synchronously determine whether it will deny wake lock of this type for this browsing context, return wakeLockPromise, abort these steps and run the deferred wake lock initialization procedure asynchronously.
  6. Create a new WakeLock object in the Realm of this Navigator object, and let wakeLock be that object.
  7. Initialize wakeLock with type type.
  8. Resolve wakeLockPromise with wakeLock and return wakeLockPromise.

When the user agent cannot synchronously determine if it will deny wake lock of the given type for the given browsing context, such as when user permission is required, the following deferred wake lock initialization procedure is performed asynchronously:

  1. If the user agent has determined that it will deny wake lock of this type for this browsing context, reject wakeLockPromise and abort these steps.
  2. Create a new WakeLock object with type type in the Realm of this Navigator object, and let wakeLock be that object.
  3. Resolve wakeLockPromise with wakeLock.

4. The WakeLock interface

The WakeLock interface allows the page to request wake locks of a particular type, to determine the current wake lock state and to receive notifications when the wake lock state is changed. 

interface WakeLock : EventTarget {
    readonly attribute WakeLockType type;
    readonly attribute boolean      active;
             attribute EventHandler onactivechange;
    WakeLockRequest createRequest();
};
type
Wake lock type associated with this WakeLock object.
active
Indicates whether wake lock if this type is currently acquired by the user agent.
onactivechange
Event handler with the corresponding event handler event type of activechange. Fired when current wake lock status indicated by the active attribute changes.

To initialize a WakeLock object of type type, the following steps MUST be performed:

  1. Set WakeLock object's type attribute to type.
  2. If the wake lock of type type is currently acquired, set the WakeLock object's active attribute to true, otherwise to false.

Internally, each WakeLock object contains request counter which is initially set to zero. Each time the createRequest() method is called on the object, the request counter is increased by one.

A WakeLock object has an outstanding wake lock request when its request counter is greater than zero.

When the createRequest() method is invoked, the following steps MUST be performed:

  1. Create a new WakeLockRequest object in the Realm of this WakeLock object and let wakeLockRequest be that object.
  2. Set wakeLockRequest's owner wake lock reference to this WakeLock object.
  3. Return wakeLockRequest.
Note
This additional WakeLockRequest object is added to address the issue with multiple components requesting wake lock on the same page independently.

5. The WakeLockRequest interface 

interface WakeLockRequest {
    void cancel();
};

Each WakeLockRequest object has an implicit owner wake lock reference to the WakeLock object through which this object was created. When the cancel() method is invoked, the following steps MUST be performed:

  1. If the cancel() method has already been invoked on this object, abort these steps.
  2. Let wakeLock be the object referred to by this object's owner wake lock reference. Decrease wakeLock's request counter by one.

6. 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. The lock is considered acquired only when the request to the operating system succeeds.

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.

A browsing context is requesting the wake lock of type type if and only if the following procedure returns true:

  1. Let navigator be the Navigator object associated with this browsing context.
  2. Let wakeLockMap be the wake lock map associated with navigator.
  3. Let wakeLockPromise be the wake lock promise for type type in wakeLockMap.
  4. If wakeLockPromise is either null, pending, or rejected, return false and abort these steps.
  5. If type is "screen" and browsing context's active document is hidden, return false and abort these steps.
  6. Let wakeLock be the object with which wakeLockPromise was resolved. If wakeLock has an outstanding wake lock request, return true, otherwise return false.
Note
The additional visibility requirement for screen wake lock is to prevent keeping the screen on when the page is not visible, such as when the browser is minimized. As this condition is transient and not under control of the web page, the specification chooses to automatically acquire and release the lock when visibility changes rather than having the page to deal with it, e.g by re-requesting the lock each time the page becomes visible again.

The wake lock is applicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge).

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

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

  1. The wake lock of type type is applicable.
  2. There is at least one browsing context that is requesting the wake lock of type type.

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

Whenever user agent acquires or releases a wake lock, the user agent MUST perform the following steps for each WakeLock object:

  1. If WakeLock object's type attribute is not equal to type, abort these steps.
  2. Queue a task which updates the WakeLock object's active attribute and fires an event named activechange at the WakeLock object.

In the task described above, the WakeLock objects's active attribute MUST be set to true if the wake lock has been acquired or to false if the wake lock has been released.

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.

Issue 1
This section needs revision considering the changes in the API. In particular, side communication channel possibility needs to be re-evaluated as wake lock state is now observable.

8. Examples

This section is non-normative.

This example acquires a screen wake lock and releases it after a while:

Example 1
navigator.getWakeLock("screen").then(function(wakeLock) {
  var request = wakeLock.createRequest();
  setTimeout(function() {
    request.cancel();
  }, 1000);
});

This example requests a screen wake lock and listens to wake lock state changes:

Example 2
var request;
navigator.getWakeLock("screen").then(function(wakeLock) {
  request = wakeLock.createRequest();
  document.getElementById("wakeLockActive").innerHTML = wakeLock.active;
  wakeLock.onactivechange = function() {
    document.getElementById("wakeLockActive").innerHTML = wakeLock.active;
  };
});

In this example, two screen wake lock requests are created and cancelled independently:

Example 3
var request1;
navigator.getWakeLock("screen").then(function(wakeLock) {
  request1 = wakeLock.createRequest();
});

// ...

var request2;
navigator.getWakeLock("screen").then(function(wakeLock) {
  request2 = wakeLock.createRequest();
});

// ...

request1.cancel();
request2.cancel();

9. Dependencies

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

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

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

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

10. Use cases

This section is non-normative.

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

11. 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 words MAY and MUST are 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

[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: https://www.w3.org/TR/dom/
[ECMASCRIPT]
Ecma International. ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[HTML]
Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. 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; Tobie Langel. W3C. Web IDL. 15 December 2016. W3C Working Draft. 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/