## Use cases 
A website wants the prevent a device from entering a power-saving state to 
allow a user to complete a task where it's not practical for the user to touch 
the screen (e.g., a maps application while driving, a VR headset like 

A website needs to be able to complete a task, but without requiring the user 
to keep the screen on (e.g., importing and processing a bunch of contacts). 
Having a wake lock on the "system" would allow the user to turn off the screen, 
while allowing a webpage (or worker) to continue processing some data in the 

A complete list of use and abuse cases can be found at [1].  
## Workarounds 
There is some evidence that "…Developers are resorting to hacks like playing 
hidden videos to prevent the screen from sleeping." [2] 

## Why now? 
There are lots of applications on the Web that would benefit from this feature. 
E.g., maps, games, cooking websites, ebooks, and sites that stream non-video 
content in real time (e.g., sports scores). Also, both Google and Mozilla are 
looking into VR, and they will likely need this (see [2]). See [1] for list of 
applications that rely on this feature in other platforms. 

Other platforms that already support this kind of feature: iOS, Android, 
Firefox OS, Windows mobile, and Tizen.  

# Proposal: 

partial interface Navigator { 
   attribute WakeLock wakeLock; 

interface WakeLock{ 
   promise request(WakeLockType type); 
   void release(WakeLockType type); 

enum WakeLockType{ "system", "display" } 

## Example 
//lock display when the recipe is showing: 
$( "#recipe" ).on( "show", function(){ 
   navigator.wakeLock.request("display").then(haveFun, boo) 
} ); 

//release lock: 
$( "#recipe" ).on( "hide", function(){ 
} ); 

## Optional enhancements 

### Timeouts  
We are thinking of adding a dictionary to hint at the system the amount of time 
it should hold the lock for (in ms). So, then the developer can express holding 
the lock for 5 minutes (e.g., ebook case, instead of having to bind a whole 
bunch of listeners and constantly having to request the wake lock). This would 
allow the UA to add whatever time the developer requested to its normal wake 
lock timer + additional time the developer might want. If the timeout is less 
than the default timeout, it can just be ignored. 

dictionary WakeLockOptions{ 
  unsigned long timeout; 

For example: 
//I only need this for ~5 mins here. 
var options = {timeout: 1000 * 60 * 5}; 
navigator.wakeLock.request("display", options);  

### Events  
It might be necessary for applications to be notified, via an event, if they've 
lost a lock after one was granted to it.  

### Check if lock is already set 
It might be useful to also have a way of checking if a lock is already set: 

readonly attribute WakeLockType? lockType  

Appreciate any feedback on the design and help with the security model.   

[1] https://w3c-webmob.github.io/wake-lock-use-cases/ 
[2] https://code.google.com/p/chromium/issues/detail?id=386255 

Reply via email to