| CARVIEW |
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.
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:
- Requesting a wake lock on the system and/or the screen and then not releasing it. For the screen wake lock, if the user does not themselves power off the screen, this would cause the user's battery to be drained more quickly than normal. Likewise with the system lock.
- Requesting a system lock, and then exploiting it to perform computationally expensive operations without the user's consent while the screen is off (e.g., mining crypto-currencies and sending results to a server).
- Combining a system lock with an API like Geolocation could allow an application to track a user while the screen is off: as the system is not actually powered-down, it could continue sending information to a server without the user's knowledge.
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:
- Why does the application need a wake lock?
- How does the user benefit?
- When is the wake lock applied and released?
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
- 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
- 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:
- FBReader on Android is configurable. It default is to only prevent sleep when battery level is greater than 50%.
Nigela's quick collections
- 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
- 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:
- iOS Maps.
Xee Photo Viewer
- 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:
- FastStone Image Viewer for Windows
- iPhoto
Firefox OS 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:
- Google Cardboard needs to stay awake since there's no direct user interaction with the screen. It would benefit from having wake-lock functionality. Mozilla's VR efforts, which rely on the Oculus Rift, would also benefit from having this API.
- The "AliveECG - Heart Monitor" for Android is an application that monitors single-channel electrocardiogram (ECG) rhythm strips. The screen that shows the beats per minute prevents the screen from locking. This allows patients and medical professionals to monitor the ECG input in real-time without needing to worry that the device will go to sleep.
- Magic The Gathering Counter stays 'awake' for users to count lives without having the screen dim while playing.
- iOS's compass application uses a wake lock to prevent the screen from going to sleep. This allows users to orient themselves without needing to worry that the screen will power off unexpectedly.
Requirements
Any specification seeking to address these requirements:
- 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.
- MUST be extensible, allowing for new types of locks to be specified in the future.
- MUST support a way for user agents to support wake locks only under specific security conditions (e.g., only in full screen).
- 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.
- MUST allow developers to release a previously requested wake lock.
- MAY allow scripts to check if an origin already holds a particular kind of lock.
- 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.
- 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.
- 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.
- 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").
- 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.