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.

Examples 

//lock display when the recipe is showing: 
$( "#recipe" ).on( "show", function() {
    navigator.wakeLock.request("screen").then(haveFun, boo); 
} ); 

//release lock: 
$( "#recipe" ).on( "hide", function() {
    navigator.wakeLock.release("screen");
    navigator.wakeLock.onlost = null;
} );

//get notified of lost locks:
function lostHandler(e){
    var msg = "oh noes! We lost the " + e.type + " lock!";   
    console.log( msg );
}

//register listener 
navigator.wakeLock.onlost = lostHandler;

Wake Locks

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

This specification deals with the following wake lock types and their expected behavior:

screen
Prevents the screen(s) of the device from entering a power-saving state.
system
Prevents the device's cpu, radio(s), and other system services from entering a power-saving state. The device's screen can dim or switch off.

Each top-level browsing context has a holding flag for a lock type T. The holding flags are initially unset. The flags are used to track if a particular top-level browsing context is holding a particular lock type.

To hold a lock of some type T means that the document of a top-level browsing context has requested, through the user agent, that the underlying system apply a particular lock type. A top-level browsing context is able to hold a lock even if the underlying operating system has not explicitly signaled that the user agent has been granted the lock.

Conversely, to release a lock of some type means that the document of a top-level browsing context has requested, through the user agent, that the underlying system no longer holds a particular lock type.

A wake lock of type T is lost when the underlying system has explicitly signaled to the user agent that it can no longer hold a particular lock type (e.g., the battery level is too low to allow a wake lock). When a lock of type T is lost, the user agent MUST run the steps to notify scripts that a lock was lost with T.

The steps to notify scripts that a lock was lost with lock type T as input:

  1. For each top-level browsing context that has a holding flag for lock type T that is set, queue a task to perform the following:
    1. Let e be a new WakeLockEvent that does not bubble, is not cancelable, has isTrusted attribute initialized to true, and whose name is lost.
    2. Set e's type attribute to T.
    3. Unset the holding flag for lock type T of the current top-level browsing context.
    4. Dispatch e at the wakeLock attribute of the current top-level browsing context.

The user agent MAY require that a top-level browsing context meet one or more security conditions in order to hold a lock. For example, the user could have indicated through the user interface that they don't wish for a web application to have this capability.

WakeLock interface

attribute EventHandler? onlost
Promise<void> request()
WakeLockType type
Promise<void> release()
WakeLockType type
boolean isHeld()
WakeLockType type

request() method

The request() method causes the user agent to requests a wake lock of a particular type from the underlying system. When called, the user agent MUST run the steps to request a wake lock with WakeLockType T as input. The algorithm returns a promise.

  1. Let p be a newly created promise.
  2. Return p and perform the following steps asynchronously.
  3. If this algorithm was not called from a top-level browsing context, or there are security conditions that prevent the user agent from holding a lock:
    1. Reject p with a DOMException whose name is SecurityError and abort these steps.
  4. If the top-level browsing context's holding flag for type T is set:
    1. ....
  5. Otherwise, attempt to attain a wake lock of the given type from the underlying system:
    1. If the system does not support wake locks of type T, reject p with a DOMException whose name is NotSupportedError.
    2. If the system rejects the request to grant the wake lock, reject p with a DOMException whose name is InvalidAccessError.
    3. Otherwise, if the grants the wake lock, resolve p with undefined.

release() method

The release() method releases a previously acquired wake lock of a particular type. When called, the user agent MUST run the steps to release a wake lock with WakeLockType T as input. The algorithm returns a promise.

  1. Let p be newly created Promise.
  2. Return p and continue asynchronously.
  3. If the top-level browsing context is holding flag for type T is unset:
    1. Reject p with a DOMException whose name is NotFoundError.
  4. Request to release lock of type T from the system.
  5. If the system cannot honor the request to release the wake lock:
    1. Reject p with a DOMException whose name is AbortError.
  6. Otherwise, resolve p with undefined.

isHeld() method

The isHeld() method provides a means to determine if the top-level browsing context is holding a particular wake lock type. When called, the user agent MUST run the steps to check if a lock is held with WakeLockType T as input. The algorithm returns a boolean.

  1. If the top-level browsing context is holding flag for type T is set, return true.
  2. Otherwise, return false.

onlost attribute

The onlost event handler provides a means for scripts of a top-level browsing context to be notified if a wake lock is lost.

WakeLockEvent interface

readonly attribute WakeLockType type

The WakeLockEvent provides a way for a script to be notified when a wake lock is lost.

type attribute

The type attribute is the WakeLockType that generated this event.

When getting, the use agent MUST return the WakeLockType that generated this event.

WakeLockType enumeration

In the API, the wake lock types are expressed as the WakeLockType enum.

screen
system

Security considerations

The primary use case for this API is to prevent a device from dimming or locking the device screen, as often happens when a device is left without user interactions.

Keeping the screen from dimming or locking can drain the underlying device power reserve. Preventing it from locking may expose the device and its content to unwanted parties if the user expected it to lock automatically.

To mitigate the risks mentioned above, user agents may want to:

Dependencies

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

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

The Promise interface is defined in [[!ECMASCRIPT]].

Use cases

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

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

Acknowledgments

I would like to offer my sincere thanks to Mounir Lamouri, Sergey Konstantinov and Matvey Larionov for their contributions to this work.