Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.
The Wake Lock API allows to take locks on any resource of the device. This means that you can prevent that resource from becoming unavailable as long as your app holds a lock for that resource. For example, a voice recording app can obtain a lock to keep the screen on during recording so that it can give prover visual feedback to the user that recording is progressing.
Gaia uses three basic resource names that can be used as topic: screen, cpu, and wifi, but any certified application can expose new resources.
Reference
Navigator.requestWakeLock()- Take a lock on a resource.
MozWakeLock- Interface representing a lock and allowing to manage them, by keeping track of it, and giving the ability to release it.
Example
Keeping the screen on
Any app can choose to keep the screen on while they are running. To achieve this, the app needs to obtain a lock for the screen resource when it is initialized.
var lock = window.navigator.requestWakeLock('screen');
App developers need to be responsible and think carefully about whether they need to keep the screen on. The risk of claiming the lock is that users may forget to close the app when they are done using it, which can result in significant increase in battery use. If you are not certain that obtaining the screen lock makes sense in all scenarios, then providing the option to enable or disable prevent screen lock option in the app settings, would be a smart move.
If you do not release the screen wake lock at all, it will be obtained again from your app when it goes to the background or when the app terminates. However there are some scenarios when you do need to release the screen lock yourself, for example when user disables the option in settings, or when the app is not performing the task that required the screen to remain on. In those scenarios you just need to call the unlock() method to release the lock.
lock.unlock();
Screen wake lock is currently available to both hosted and packaged apps running on the Firefox OS platform.
Specification
Not part of any specification