Can’t make the #ChromeDevSummit this year? Catch all the content (and more!) on the livestream, or join your peers for a CDS Extended event at a hosted location nearby. To learn more, check out the Chrome Dev Summit 2019 website.

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

Step Status
1. Create explainer Complete
2. Create initial draft of specification Complete
3. Gather feedback & iterate on design In Progress
4. Origin trial Not Started
5. Launch Not Started

How to use the Wake Lock API

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.

screen wake lock

A screen wake lock prevents the device’s screen from turning off so that the user can see the information that’s displayed on screen.

system wake lock

A system wake lock prevents the device’s CPU from entering standby mode so that your app can continue running.

Get a wake lock

To request a wake lock, you need to call the WakeLock.request() method that lives on the window object. You pass it the desired wake lock type as the first parameter, which currently is limited to just 'screen'. In addition, you also need a way to abort the wake lock, which works through the generic AbortController interface. Therefore, you first create a new AbortController, and then pass the controller’s AbortSignal as the second parameter to WakeLock.request(). Two things can happen next that you need to catch:

  • The wake lock can, after a while, just be regularly aborted, which you detect by checking if the exception’s name is 'AbortError'. In this context, AbortError is actually not an error in the common sense, but just the way AbortController works.
  • The browser can also refuse the request for different reasons, for example, because the battery charge level is too low. In this case, the exception’s message will contain more details.
const wakeLockCheckbox = document.querySelector('#wakeLockCheckbox');

if ('WakeLock' in window) {
  let wakeLock = null;

  const requestWakeLock = () => {
    const controller = new AbortController();
    const signal = controller.signal;
    window.WakeLock.request('screen', {signal})
    .catch((e) => {
      if (e.name === 'AbortError') {
        wakeLockCheckbox.checked = false;
        console.log('Wake Lock was aborted');
      } else {
        console.error(`${e.name}, ${e.message}`);
      }
    });
    wakeLockCheckbox.checked = true;
    console.log('Wake Lock is active');
    return controller;
  };

  wakeLockCheckbox.addEventListener('change', () => {
    if (wakeLockCheckbox.checked) {
      wakeLock = requestWakeLock();
    } else {
      wakeLock.abort();
      wakeLock = null;
    }
  });
}

The wake lock lifecycle

When you play with the wake lock demo, you'll notice that wake locks are sensitive to page visibility changes as defined by the Page Visibility API, as well as full screen changes defined by the Fullscreen API. This means that when you minimize a tab or window where a wake lock is active or enter full screen mode, the wake lock will automatically abort. If you want your wake lock to be re-acquired, you need to listen for the events that either of the APIs emit, namely the visibilitychange event of the Page Visibility API and the fullscreenchange event of the Fullscreen API, and then request a new wake lock.

const handleVisibilityChange = () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    wakeLock = requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);
document.addEventListener('fullscreenchange', handleVisibilityChange);

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.

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.

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.

Helpful Links

rss_feed Subscribe to our RSS or Atom feed and get the latest updates in your favorite feed reader!

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.