Wake Lock API

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 is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/wake-lock/ for the Editor's draft.

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 an Editor's Draft.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-device-apis@w3.org (archives).

Please see the Working Group's implementation report.

Publication as an Editor's 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 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 February 2018 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:

Screen wake lock which prevents device's screen from turning off so that the user can still see the information displayed on the screen.
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 can deny wake lock of a particular type for a particular Document by any implementation-specific reason, for example, a user or platform setting or preference.

The wake lock feature is a policy-controlled feature with feature name wake-lock and default allowlist ["self"].

Note

The default allowlist of ["self"] allows wake lock usage in same-origin nested frames but prevents third-party content from using wake locks.

Third-party usage can be selectively enabled by adding allow="wake-lock" attribute to the frame container element:

Example 1

<iframe src="https://third-party.com" allow="wake-lock"/></iframe>

Alternatively, the wake lock feature can be disabled completely by specifying the feature policy in a HTTP response header:

Example 2

Feature-Policy: {"wake-lock": []}

See [FEATURE-POLICY] for more details.

Internal Slot	Initial value	Description (non-normative)
[[RequestCounter]]	A set with entries for each wake lock type with the values equal to 0.	The values indicates the amount of current requests per wake lock type. A number greater than zero indicates an outstanding wake lock request

4. Extensions to the `Navigator` interface

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

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

Let document be the responsible document of the current settings object.
Let context be the document's browsing context.
If context is null, return a new Promise object, rejected with a "NotSupportedError" DOMException.
Let p be a new Promise object.
If document is not allowed to use the policy-controlled feature named "wake-lock", reject p with a "SecurityError" DOMException and return p.
Run the following steps in parallel:
1. If the user agent denies the wake lock of this type for document, reject p with "NotSupportedError" and abort these steps.
2. Let lock be the result of create and initialize a wake lock object of type type.
3. Resolve p with lock.
Return p.

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

[SecureContext, Exposed=Window] interface WakeLock : EventTarget {
  readonly attribute WakeLockType type;
  readonly attribute boolean active;
  attribute EventHandler onactivechange;
  void request(optional WakeLockRequestOptions options);
};

type: Wake lock type associated with this WakeLock object.
active: Indicates whether wake lock of 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 create and initialize a WakeLock object of type type, the following steps MUST be performed:

Let lock be a new WakeLock object.
Set lock's type to type.
If the wake lock of type type is currently acquired, set lock's active to true, otherwise to false.
Return lock.

5.1 The `WakeLockRequestOptions` dictionary

dictionary WakeLockRequestOptions {
  AbortSignal? signal;
};

The WakeLockRequestOptions.signal property allows to abort any wake lock request.

The request() method, when invoked, MUST run the following algorithm:

Let options be the first argument.
Let signal be the options’ dictionary member of the same name if present, or null otherwise.
Let record be the current settings object's associated wake lock state record.
If signal’s aborted flag is set, abort these steps.
If signal is not null, then add the following abort steps to signal:
1. Decrease record.[[RequestCounter]][type] by one.
2. If record.[[RequestCounter]][type] is 0, then run the following steps in parallel:
  1. Run release a wake lock on this.
If this's type is "screen", run the following steps:
1. Let document be the responsible document of the current settings object.
2. If document is hidden, abort these steps.
Increase record.[[RequestCounter]][type] by one.
If record.[[RequestCounter]][type] is 1, run the following steps in parallel:
1. Run Acquire a wake lock on this.

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.

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.

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 swiched off by the user until it is switched on again. Manually switching off the screen MUST NOT affect the applicability of the system wake lock.

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.

6.1 Acquire wake lock algorithm

To acquire a wake lock for a given WakeLock object lock, run these steps in parallel:

Let type be lock's type.
If the wake lock for type type is not applicable, return false.
Ask the underlying operation system to acquire the wake lock of type type and let success be true if the operation succeeded, or else false.
If success is different from lock's active, set lock's active to success and fire an event named "activechange" at lock.
Return success.

6.2 Release wake lock algorithm

To release a wake lock for a given WakeLock object lock, run these steps in parallel:

Let type be lock's type.
Ask the underlying operation system to release the wake lock of type type and let success be true if the operation succeeded, or else false.
If success is different from lock's active, set lock's active to the negated success and fire an event named "activechange" at lock.
If lock's type is "screen" run the following:
1. The user agent MUST reset the platform-specific inactivity timer after which the screen is actually turned off.
Return success.

Note

Resetting the inactivity timer prevents the screen from going blank immediately after the wake lock is 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.

The ability to observe the global state of a wake lock can create a communication channel between two otherwise isolated documents. One document can request wake lock which changes the global wake lock state, and another document can observe this change by subscribing to events in WakeLock.

When the user agent does not acquire wake lock even though a browsing context has requested it, this can be observed by the browsing context and can possibly disclose sensitive information about the state of the device such as that battery level is low.

8. Examples

This section is non-normative.

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

Example 3

async function tryKeepScreenAlive(minutes) {
  const lock = await navigator.getWakeLock("screen");

  const controller = new AbortController();
  const signal = controller.signal;

  lock.request({ signal });

  setTimeout(() => controller.abort(), minutes * 60 * 1000);
}

tryKeepScreenAlive(10);

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

Example 4

const controller = new AbortController();
const signal = controller.signal;

const checkbox = document.createElement("input");
checkbox.setAttribute("type", "checkbox");
document.body.appendChild(checkbox);

navigator.getWakeLock("screen").then(lock => {
  lock.onactivechange = () => {
    checkbox.checked = lock.active;
  };
  lock.request({ signal });
});

setTimeout(() => controller.abort(), 5 * 1000);

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

Example 5

const controller = new AbortController();
const signal = controller.signal;

const p1 = navigator.getWakeLock("screen");
const p2 = navigator.getWakeLock("screen");

p1.then(lock => lock.request({ signal }));

// ...somewhere else

p2.then(lock => lock.request({ signal }));

// ...somewhere else

controller.abort();

C. References

C.1 Normative references

[DOM]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]: ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
[FEATURE-POLICY]: Feature Policy. WICG. Living Standard. URL: https://wicg.github.io/feature-policy/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]: Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[PAGE-VISIBILITY]: Page Visibility (Second Edition). Jatinder Mann; Arvind Jain. W3C. 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]: Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

C.2 Informative references

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

Wake Lock API

W3C Editor's Draft 28 February 2019

Abstract

Status of This Document

1. Wake Locks

2. The `WakeLockType` enum

3. Wake lock state associated with the settings object

4. Extensions to the `Navigator` interface

5. The `WakeLock` interface

5.1 The `WakeLockRequestOptions` dictionary

6. Managing Wake Locks

6.1 Acquire wake lock algorithm

6.2 Release wake lock algorithm

7. Security and privacy considerations

8. Examples

9. Dependencies

10. Use cases

11. Conformance

A. IDL Index

B. Acknowledgments

C. References

C.1 Normative references

C.2 Informative references

Wake Lock API

W3C Editor's Draft 28 February 2019

Abstract

Status of This Document

1. Wake Locks

2. The WakeLockType enum

3. Wake lock state associated with the settings object

4. Extensions to the Navigator interface

5. The WakeLock interface

5.1 The WakeLockRequestOptions dictionary

6. Managing Wake Locks

6.1 Acquire wake lock algorithm

6.2 Release wake lock algorithm

7. Security and privacy considerations

8. Examples

9. Dependencies

10. Use cases

11. Conformance

A. IDL Index

B. Acknowledgments

C. References

C.1 Normative references

C.2 Informative references

2. The `WakeLockType` enum

4. Extensions to the `Navigator` interface

5. The `WakeLock` interface

5.1 The `WakeLockRequestOptions` dictionary