I’m Awake! Stay Awake with the WakeLock API

What is the Wake Lock API?

To avoid draining the battery, most devices quickly go to sleep when left idle. While this is fine most of the time, some applications need to keep the screen or the device awake in order to complete their work. For example, a run-tracking app (turns the screen off, but keeps the system awake), or a game, like Ball Puzzle, that uses the device motion APIs for input.

The Wake Lock API provides a way to prevent the device from dimming and locking the screen or prevent the device from going to sleep. This capability enables new experiences that, until now, required a native app.

The Wake Lock API aims to reduce the need for hacky and potentially power-hungry workarounds. It addresses the shortcomings of an older API which was limited to simply keeping the screen on, and had a number of security and privacy issues.

Suggested use cases for the Wake Lock API

RioRun a web app developed by The Guardian that takes you on a virtual audio tour of Rio, following the route of the 2016 Olympic marathon would be a perfect use case. Without wake locks, your screen will turn off frequently, making it hard to use.

Of course, there are plenty of others:

• Kiosk-style apps where it’s important to prevent the screen from turning off.
• Web based presentation apps where it’s essential to prevent the screen from going to sleep while in the middle of a presentation.

Current status

Note: Big thanks to the folks at Intel, specifically Mrunal Kapade for doing the work to implement this. We depend on a community of committers working together to move the Chromium project forward. Not every Chromium committer is a Googler, and they deserve special recognition!

How to use the Wake Lock API

Dogfood: We’re still working on the Wake Lock API, and it’s only available behind a flag (#enable-experimental-web-platform-features). While in development, bugs are expected, or it may fail to work completely.

Check out the Wake Lock demo and source for the demo.

Wake lock types

The Wake Lock API provides two types of wake locks, screen and system. While they are treated independently, one may imply the effects of the other. For example, a screen wake lock implies that the app should continue running.

Get a wake lock object

In order to use the Wake Lock API, we need to create and initialize a wakelock object for the type of wake lock we want. Once created, the promise resolves with a wakelock object, but note, the wake lock isn’t active yet, it’ll need to be activated first.

let wakeLockObj;
if ('getWakeLock' in navigator) {
  try {
    // Create a wake lock for the type we want.
    wakeLockObj = await navigator.getWakeLock('screen');
    console.log('👍', 'getWakeLock', wakeLockObj);
  } catch (ex) {
    console.error('👎', 'getWakeLock', err);
  }
}

In some instances, the browser may fail to create the wake lock object, and instead throws an error, for example if the batteries on the device are low.

Use the wake lock object

We can use the newly created wakeLockObj to activate a lock, or determine the current wake lock state and to receive notifications when the wake lock state is changed.

To acquire a wake lock, we simply need to call wakeLockObj.createRequest(), which creates a new WakeLockRequest object. The WakeLockRequest object allows multiple components on the same page to request their own locks. The WakeLock object automatically handles the requests. The wake lock is released when all of the requests have been cancelled.

let wakeLockRequest;
function toggleWakeLock() {
  if (wakeLockRequest) {
    // Stop the existing wake lock request.
    wakeLockRequest.cancel();
    wakeLockRequest = null;
    return;
  }
  wakeLockRequest = wakeLockObj.createRequest();
  // New wake lock request created.
}

Caution: It’s critical to keep a reference to wakeLockRequest created by wakeLockObj.createRequest() in order to release the wake lock later. If the reference to the wakeLockRequest is lost, you won’t be able to cancel the wake lock until the page is closed.

You can track if a wake lock is active by listening for the activechange event on the WakeLock object.

wakeLockObj.addEventListener('activechange', () => {
  console.log('⏰', 'wakeLock active:', wakeLockObj.active);
});

Best Practices

The approach you take depends on the needs of your app. However, you should use the most lightweight approach possible for your app, to minimize your app's impact on system resources.

Before adding wake lock to your app, consider whether your use cases could be solved with one of the following alternative solutions:

• If your app is performing long-running downloads, consider using background fetch.
• If your app is synchronizing data from an external server, consider using background sync.

Note: Like most other powerful web APIs, the Wake Lock API is only available when served over HTTPS.

Feedback

We need your help to ensure that the Wake Lock API works in a way that meets your needs and that we’re not missing any key scenarios.

What should the permission model look like? When should the browser notify the user that there’s a wake lock active? Add your thoughts to how should UAs infer consent to take a wakelock GitHub issue.

If there are any features we’re missing, or there are scenarios that are either difficult or impossible to implement with the current design, please file an issue in the w3c/wake-lock repo and provide as much detail as you can.

We’re also interested to hear how you plan to use the Wake Lock API:

• Have an idea for a use case or an idea where you'd use it?
• Do you plan to use this?
• Like it and want to show your support?

Share your thoughts on the Wake Lock API WICG Discourse discussion.

Helpful Links

• Specification Candidate Recommendation | Editor’s Draft
• Wake Lock Demo | Wake Lock Demo source
• Tracking bug
• ChromeStatus.com entry
• Experimenting with the Wake Lock API
• Blink Component: Blink>WakeLock