Learn Measure Blog About

Stay awake with the Wake Lock API

The Wake Lock API provides a way to prevent devices from dimming or locking the screen when an application needs to keep running.

Updated
Pete LePage
Pete LePage
Thomas Steiner
Thomas Steiner

The Wake Lock API, part of Google's capabilities project, is currently in development. This post will be updated as the implementation progresses.

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 to complete their work. Examples include a run-tracking app, which turns the screen off but keeps the system awake, or a game like Ball Puzzle, which 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 going to sleep. This capability enables new experiences that, until now, required a native app.

The Wake Lock API reduces the need for hacky and potentially power-hungry workarounds. It addresses the shortcomings of an older API that 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, was a perfect use case (though it's no longer available). The app takes you on a virtual audio tour of Rio, following the route of the 2016 Olympic marathon. Without wake locks, users' screens would turn off frequently while the tour played, making it hard to use.

Of course, there are plenty of other use cases:

  • A recipe app that keeps the screen on while you bake a cake or cook dinner
  • A boarding pass or ticket app that keeps the screen on until the barcode has been scanned
  • A kiosk-style app that keeps the screen on continuously
  • A web-based presentation app that keeps the screen on during a presentation

Current status

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

Big thanks to the folks at Intel, specifically Mrunal Kapade, for implementing this API. Chrome depends on a community of committers working together to move the Chromium project forward. Not every Chromium committer is a Googler, and these contributors deserve special recognition!

Using the Wake Lock API

The Wake Lock API is currently in development and is only available in Chrome behind a flag. To experiment with the Wake Lock API, enable the #enable-experimental-web-platform-features flag in chrome://flags.

Check out the Wake Lock demo and demo source.

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

Caution: The system wake lock is not currently implemented.

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 navigator.wakeLock.request() method that returns a WakeLockSentinel object. You pass this method the desired wake lock type as a parameter, which currently is limited to just 'screen'. The browser can refuse the request for various reasons (for example, because the battery charge level is too low), so it's a good practice to wrap the call in a try…catch statement. The exception's message will contain more details in case of failure.

You also need a way to release the wake lock, which is achieved by calling the release() method of the WakeLockSentinel object. If you don't store a reference to the WakeLockSentinel, there's no way to release the lock manually, but it will be released once the current tab is invisible.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a wake lock.
const requestWakeLock = async () => {
try {
wakeLock = await navigator.wakeLock.request('screen');
wakeLock.addEventListener('release', () => {
console.log('Wake Lock was released');
});
console.log('Wake Lock is active');
} catch (err) {
console.error(`${err.name}, ${err.message}`);
}
};

// Request a wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
wakeLock.release();
wakeLock = null;
}, 5000);

The wake lock lifecycle

When you play with the wake lock demo, you'll notice that wake locks are sensitive to page visibility and full-screen mode. This means that the wake lock will automatically be released when you enter full-screen mode, minimize a tab or window, or switch away from a tab or window where a wake lock is active.

To reacquire the wake lock, listen for the visibilitychange event and the fullscreenchange event and request a new wake lock when they occur:

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

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

Minimize your impact on system resources

Should you use a wake lock in your app? The approach you take depends on the needs of your app. Regardless, you should use the most lightweight approach possible for your app to minimize its 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.

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

Feedback

The Web Platform Incubator Community Group (WICG) and the Chrome team want to hear about your thoughts and experiences with the Wake Lock API.

Tell us about the API design

Is there something about the API that doesn't work as expected? Or are there missing methods or properties that you need to implement your idea?

Report a problem with the implementation

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?

  • File a bug at https://new.crbug.com. Be sure to include as much detail as you can, provide simple instructions for reproducing the bug, and set Components to Blink>WakeLock. Glitch works great for sharing quick and easy repros.

Show support for the API

Are you planning to use the Wake Lock API? Your public support helps the Chrome team prioritize features and shows other browser vendors how critical it is to support them.

Helpful links

Last updated: Improve article