This document illustrates the use cases a mechanism to control the power-saving state of a device would enable on the Web platform.

This is a work in progress. You can contribute to this specification by contributing additional use cases through our GitHub repository.

Introduction

The web platform currently lacks a means to prevent a device from entering a power-saving state (i.e., some means that prevents an aspect of the system from "going to sleep"). As this document tries to demonstrate, there are strong use cases where applications need to temporarily prevent some aspect of the device from entering a power-saving state. As this functionality is common on other platforms, this document tries to make the case that this functionality should also be made available to the web platform.

To understand the use cases that motivate an application from preventing a device from entering a power-saving state we examined a set of applications running on iOS, Android, and Firefox OS. By looking at these native applications, and the conditions under which they prevent a device from entering a power-saving state, we've come up with a set of requirements. We hope that the web community can address these requirements by creating a specification that affords similar functionality to the web platform.

Why we need wake locks on the Web

For tasks such as watching a video full-screen user agents have, for a long time now, prevented the screen from going to sleep automatically. Naturally users would be annoyed if they were watching a movie and constantly needed to move a mouse or poke at the screen of a device to stop the screen from going black.

Keeping the screen awake

As computing devices have become increasingly mobile, users find themselves relying on mobile devices to assist them with everyday tasks where it is not always practical or desirable to touch the device to keep it "awake". These can be simple things, like using the phone as a flashlight, to complex tasks such as cooking or allowing the phone to navigate us to some destination while driving. In addition, touch enabled devices have become commodified enough that they can be used as interactive signage. Some of these use cases are illustrated in the figure below.

Examples of tasks and contexts in which it is necessary to prevent the screen from going to sleep: from right to left, navigation from one location to another, reading an e-book, preparing a meal by following a recipe, and using a touch-enabled device as signage. In this final case, the device displays if a particular meeting room is booked - and allows users to manage booking a room by interacting with the screen, which is always on.

Keeping the system awake

On the flip-side, keeping the screen on is not the only kind of "wake lock" applications require. There is also use cases that there needs to be a kind of lock that also keeps the system awake for a short amount of time to allow arbitrary tasks to complete. It is well-known that, under normal conditions, the display of a device consumes a high percentage of a device's battery. Only keeping the screen on when absolutely necessary can greatly assist in prolonging the battery life of a device throughout a day.

As mobile devices are generally not as powerful as desktop class machines, and because of the uncertain network conditions under which these devices operate, some tasks can take a long time to complete - longer than users are willing to wait before putting their device back into their pocket, or sometimes longer than the default timeout most devices have to put the screen to sleep (e.g., 1 minute or there abouts). Consider importing and processing a set of contacts over a slow network connection, which can sometimes take minutes. It would be unrealistic to expect the user to hold their phone in their hand while they wait for a synchronization task to complete: users should be able to switch off the screen of a device and trust that an application will do its best to complete a certain task in the background.

In other words the user shutting off the screen doesn't mean that an application must stop running and have the device enter a low-power state. An application may need to intervene and finish what it's doing or it risks data-loss. In another concrete example a user may compose an email with a large photo attachment. When they press send they just as quickly press the power button to turn off the screen and put the phone back in their pocket. In such a situation, as happens with iOS's mail app, the application continues to run by sending the email before putting the phone in a low-power state. Note that this system level lock includes keeping the WiFi and cellular radio from also shutting down or entering a low power state while some task is being performed.

Potential for abuse

As with any device API on the Web, there is the risk that this API could be intentionally or unintentionally abused by developers.

Abuse cases include, but are not limited to:

Ultimately, it will be up to user agents to mitigate these sorts of abuse cases. However, the design of the API may also assist in mitigating certain kinds of abuses.

Current workarounds

To overcome the lack of support for wake locks in the platform, there is hearsay evidence that …Developers are resorting to hacks like playing hidden videos to prevent the screen from sleeping.

Methodology and limitations

We used convenience sampling to select the applications in this document. That is, we selected applications that we knew prevented the screen from going to sleep when the application was being used to perform some particular action. We also reached out to people on twitter for suggestions as to which applications we should look at. Suggestions were captured as "issues" in our GitHub repository.

As stated on Wikipedia's entry about convenience sampling: "[one] cannot scientifically make generalizations about the total population from this sample because it would not be representative enough." Regardless, we view the range of applications we collected as exemplifying common use cases for this kind of functionality. As such, we still created requirements from what we observed across applications and other platforms. We encourage the community to contribute more, or contradictory/abuse-cases, examples to the Web and Mobile IG. You can do this via a pull request to the screen-wake repository on GitHub.

How we looked at the apps

For each application, we asked:

Support on various platforms

Below is a list of APIs from native platforms that developers can make use of to prevent a device from going to sleep. The list shows that this functionality is commonly available to developers without significant security restrictions. It is important to note that some platforms differentiate between putting the system to sleep and putting the display to sleep. Requesting that the system (or "CPU") not sleep while allowing the display to sleep allows long running tasks to complete.

iOS:
UIApplication.idleTimerDisabled.
Android:
Wake locks: supports both CPU and display.
Windows 8
Idle detection for Windows Phone 8
FirefoxOS:
navigator.requestWakeLock() - Supports "cpu", "display", and "wifi".
ChromeApps:
chrome.power.requestKeepAwake() - supporting both "system" and "display".
Tizen:
tizen.power.request(). Note that Tizen supports both "screen" and "cpu".

Brazil 2014

The "Brazil 2014" iOS app allows users to keep up with news related to the 2014 World Cup.
Why does the application need a wake lock?
The application allows users to follow football matches in real-time: receiving updates as the match is taking place. Allowing users to follow the action in real-time seems to be the primary motivator.
How does the user benefit?
During a match, the user can simply place their device on a surface for convenient viewing - or they can simply hold the device in their hand. Without requiring any user interaction light-weight textual and graphical information is streamed to the device and automatically displayed on screen. This means that the user does not need to interact directly with the device to receive updates of what is happening during a match. Note that this application does not stream live video.
When is the wake lock applied and released?
The wake lock is only applied when the user opens the "action" screen of the application and if, and only if, a match is actually taking place. The wake lock is released as soon as match is finished.

Google Play Books

Books on Google Play is an Android application for managing and reading a collection of e-books.
Why does the application need a wake lock?
The Screen stays 'awake' allowing users to continue reading and e-book without having to continuously poke at the screen to keep the device awake.
How does the user benefit?
Allows a user the read at their own pace without needing to constantly poke the screen to keep it awake. It also means that users can keep their hands away from the screen until they need to turn the page.
When is the wake lock applied and released?
The lock is applied only once the user opens a book. It is released once the user returns to the book selection menu. Additionally, if the user doesn't turn the page of a book after about 5 minutes, the application automatically releases the wake lock.

Applications that exhibit similar behavior:

Nigela's quick collections

Nigela's quick collections is a cooking application that contains a collection of recipes and a set of steps for how to prepare each dish.
Why does the application need a wake lock?
Allowing users to prepare dishes while simultaneously interacting with the recipes of the application (recipes are spread across multiple screens and require multiple steps to be followed in order). A user may find it annoying if the device went to sleep while they were trying to follow a recipe (as this involves a lot of multitasking on the side of the user, their hands might not be available, or their hands might be dirty or wet).
How does the user benefit?
As the user's hands could be dirty or wet, the app keeps the screen on and allows the user to navigate the application using voice commands instead.
When is the wake lock applied and released?
The wake lock is only engaged when the user explicitly opens up a recipe. When the user leaves a recipe and returns to, say, the main screen, the wake lock is released.

Other applications that exhibit similar behavior:

Google Maps

Google maps on iOS is a popular maps application that supports turn by turn navigation.
Why does the application need a wake lock?
Safety. Keeping the screen on allows the user to periodically glance at their phone to get oriented while navigating to their destination. On iOS, even if the user turns off the screen, the application continues to run and notifies the when they need to make a turn.
How does the user benefit?
When in navigation mode, the screen will stay 'awake' so users do not need to physically interact with the device when navigating.
When is the wake lock applied and released?
The screen lock is only applied when the user begins navigating. The screen lock is released when the user stops navigating or reaches their destination.

Other applications that exhibit similar behavior:

Xee Photo Viewer

Xee is an application for viewing images. It provides a "slideshow" mode, which automatically presents a sequence of images in full screen.
Why does the application need a wake lock?
The wake lock makes sure that the screen does not switch off in the middle of the slideshow.
How does the user benefit?
Becasue the screen stays 'awake', users do not need to physically interact with the device to ensure the slideshow continues running. This leaves the user free to interact with others whom may also be viewing the images in the same physical space.
When is the wake lock applied and released?
The screen lock is only applied when the user starts the slideshow. The wake lock is released when the slideshow reaches the last photo in a set or it gets interrupted by the user.

Other applications that exhibit similar behavior:

Firefox OS Contacts

Firefox OS's contacts application allows a user to manage contacts, as well as import friends from Facebook as contacts.
Why does the application need a wake lock?
To be able to import contacts and performing long-lived tasks without requiring the user to keep the screen on.
How does the user benefit?
The user is assured that importing contacts will complete without needing to keep the screen on. This conserves battery.
When is the wake lock applied and released?
When the import task is complete.

Other applications

A range of other applications benefit, or could benefit, from a wake lock. For instance:

Requirements

Any specification seeking to address these requirements:

  1. MUST support requesting a wake lock on at least the system and on the display. The display being the screen or primary output modality of the device. The system meaning that the device can put the screen to sleep, but MUST continue running a task until an application releases the lock on the system. Keeping the screen awake MUST (obviously) also keep the system awake.
  2. MUST be extensible, allowing for new types of locks to be specified in the future.
  3. MUST support a way for user agents to support wake locks only under specific security conditions (e.g., only in full screen).
  4. MUST support a means for scripts to be notified if a request for a lock fails to be granted. And if a lock request is not granted, the UA SHOULD provide the developer and script with appropriate information detailing why the request was not granted.
  5. MUST allow developers to release a previously requested wake lock.
  6. MAY allow scripts to check if an origin already holds a particular kind of lock.
  7. MUST make the user agent ultimately responsible for managing the wake locks. The user agent MAY automatically release the lock for security reasons, and MUST release all locks when an application is closed or navigated to another origin. It MAY also release the lock after some amount of inactivity.
  8. MUST NOT be applied solely at the application level (e.g., just once when the application starts). Instead, developers MUST be able to request wake locks at arbitrary moments in time to help the user complete a task.
  9. MUST be possible for the end user to override the wake lock on the screen (e.g., by pressing the power button on the device, which puts the screen to sleep). Applications SHOULD be notified when such a thing happens, so they can request a system lock if they need to complete some task.
  10. MAY allow a means to hint to the user agent how long a lock is to be held (e.g., "keep the screen on for at least 5 mins").
  11. MUST allow the end user to have ultimate control over which documents have control over a wake locks (e.g., not allowing a page to get get any kind of wake lock without user opt-in).

Observations

The following are a set of related observation we made while we were preparing this document.

In iOS, an orientation change can serve as a trigger to prevent the screen from locking. However, this only works on apps that support changes in orientation. This is not the case in Android, where changing the orientation of the device has no effect - even if the application supports multiple orientations.

Acknowledgments

Huge thanks to Ehsan Akhgari, Seth Ladd, Ian Hickson, Boris Smus, Damon Douglas, Ilya Bogdanovich, Tab Atkins, and Domenic Denicola.