[whatwg] Proposal: Wake Lock API

## 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 Cardboard).  

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 background.     

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(){ 
   navigator.wakeLock.release("display") 
} ); 

## 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

Received on Tuesday, 15 July 2014 19:22:30 UTC