No substantial changes have been made to the Battery Status API since the W3C Candidate Recommendation of December 2014 (diff) , however the document now has more detailed privacy considerations, including advice regarding the implications of high precision readouts, based on feedback from implementation experience. It also has updated references.
The implementation report of the API shows all features have been implemented by two independent deployed browsers, meeting the CR exit criteria. We had no CR features marked as 'at-risk'.
There is a known issue with some WebIDL implementations that are not specific to the Battery Status API; the interoperability effect of that issue is minimal, since it only affects error handling in case where the API is mis-used, which is in practice detected at development time rather than usage time.
The Battery Status API specification defines a means for web developers to programmatically determine the battery status of the hosting device. Without knowing the battery status of a device, a web developer must design the web application with an assumption of sufficient battery level for the task at hand. This means the battery of a device may exhaust faster than desired because web developers are unable to make decisions based on the battery status. Given knowledge of the battery status, web developers are able to craft web content and applications which are power-efficient, thereby leading to improved user experience. Authors should be aware, however, that a naïve implementation of this API can negatively affect the battery life.
The Battery Status API can be used to defer or scale back work when the device is not charging in or is low on battery. An archetype of an advanced web application, a web-based email client, may check the server for new email every few seconds if the device is charging, but do so less frequently if the device is not charging or is low on battery. Another example is a web-based word processor which could monitor the battery level and save changes before the battery runs out to prevent data loss.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.
The following concepts, terms, and interfaces are defined in [[!HTML]], [[!DOM]], [[!ECMASCRIPT]], [[!WEBIDL]], and [[!SECURE-CONTEXTS]]:
Navigator
EventHandler
EventTarget
Document
SecurityError
NotAllowedError
DOMException
The API defined in this specification is used to determine the battery status of the hosting device.
The user agent SHOULD not expose high precision readouts of battery status information as that can introduce a new fingerprinting vector.
The user agent MAY ask the user for battery status information access, or alternatively, enforce the user permission requirement in its private browsing modes.
The user agent SHOULD inform the user of the API use by scripts in an unobtrusive manner to aid transparency and to allow the user to revoke the API access.
The user agent MAY obfuscate the exposed value in a way that authors cannot directly know if a hosting device has no battery, is charging or is exposing fake values.
partial interface Navigator { Promise<BatteryManager> getBattery(); };
For each Navigator object, there is a battery
promise, which is initially set to null
. It is a
Promise object which holds a BatteryManager.
The getBattery()
method, when invoked, MUST run
the following steps:
Document
is not allowed to use
the battery
feature, then reject this Navigator
object's battery promise with a "NotAllowedError"
DOMException, return this Navigator object's battery
promise and abort these steps.
Document
's browsing context's active
document's origin is not same origin-domain with
the origin of the current settings object of this
Navigator object, unless specifically allowed by the
document's feature policy.
null
, return this Navigator object's battery
promise and abort these steps.
BatteryManager
object in the
Realm of this Navigator object, and let
battery be that object.
The BatteryManager interface represents the current
battery status information of the hosting device. The
charging
attribute represents the charging state of the system's battery. The
chargingTime
attribute represents the time remaining in seconds until the system's
battery is fully charged. The dischargingTime
attribute
represents the time remaining in seconds until the system's battery is
completely discharged and the system is about to be suspended, and the
level
attribute
represents the level of the system's battery.
[Exposed=Window] interface BatteryManager : EventTarget { readonly attribute boolean charging; readonly attribute unrestricted double chargingTime; readonly attribute unrestricted double dischargingTime; readonly attribute double level; attribute EventHandler onchargingchange; attribute EventHandler onchargingtimechange; attribute EventHandler ondischargingtimechange; attribute EventHandler onlevelchange; };
When the user agent is to create a new
BatteryManager
object, it MUST instantiate a new
BatteryManager object and set its attributes' values to those
that represent the current battery status information, unless
the user agent is unable to report the battery status
information, in which case the values MUST be set to default
values as follows: charging
MUST be set to true,
chargingTime
MUST be set to 0,
dischargingTime
MUST be set to positive Infinity, and
level
MUST be set to 1.0.
The user agent is said to be unable to report the battery status information, if it is not able to report the values for any of the attributes, for example, due to a user or system preference, setting, or limitation.
Implementations unable to report the battery status information emulate a fully charged and plugged in battery to reduce the potential for fingerprinting and prevent applications from degrading performance, if the battery status information is not made available, for example.
The charging
attribute
MUST be set to false if the battery is discharging, and set to true, if
the battery is charging, the implementation is unable to report the
state, or there is no battery attached to the system, or otherwise.
When the battery charging state is updated, the user agent MUST
queue a task which sets the charging
attribute's
value and fires an event named
chargingchange
at the BatteryManager object.
The chargingTime
attribute MUST be set to 0, if the battery is full or there is no
battery attached to the system, and to the value positive Infinity if
the battery is discharging, the implementation is unable to report the
remaining charging time, or otherwise. When the battery charging time
is updated, the user agent MUST queue a task which sets
the chargingTime
attribute's value and fires an event named chargingtimechange
at the
BatteryManager object.
The dischargingTime
attribute
MUST be set to the value positive Infinity, if the battery is charging,
the implementation is unable to report the remaining discharging time,
there is no battery attached to the system, or otherwise. When the
battery discharging time is updated, the user agent MUST
queue a task which sets the dischargingTime
attribute's value and fires an event named
dischargingtimechange
at the BatteryManager
object.
The level
attribute MUST be
set to 0 if the system's battery is depleted and the system is about to
be suspended, and to 1.0 if the battery is full, the implementation is
unable to report the battery's level, or there is no battery attached
to the system. When the battery level is updated, the user agent
MUST queue a task which sets the level
attribute's
value and fires an event named
levelchange
at the BatteryManager object.
The definition of how often the chargingtimechange
,
dischargingtimechange
, and
levelchange
events are fired is left to the
implementation.
If a hosting device contains more than one battery, BatteryManager SHOULD expose an unified view of the batteries.
The charging
attribute MUST be set to true if at least
one battery's charging
state as described above is true.
Otherwise, it MUST be set to false.
The chargingTime
attribute can be set to the maximum
charging time of the individual batteries if charging in parallel,
and to the sum of the individual charging times if charging serially.
The dischargingTime
attribute can be set to the maximum
discharging time of the individual batteries if discharging in
parallel, and to the sum of individual discharging times if
discharging serially.
The level
attribute can be set to the average of the
levels of batteries of same capacity, or the weighted average of the
battery level attributes for batteries of different capacities.
The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the BatteryManager object:
event handler | event handler event type |
---|---|
onchargingchange
|
chargingchange
|
onchargingtimechange
|
chargingtimechange
|
ondischargingtimechange
|
dischargingtimechange
|
onlevelchange
|
levelchange
|
The Battery Status API is a policy-controlled feature identified
by the string "battery
". It's default allowlist is
'self'
. When disabled in a document, the
getBattery()
method MUST return a promise
which rejects with a "SecurityError" DOMException.
This trivial example writes the battery level to the console each time the level changes:
// We get the initial value when the promise resolves ... navigator.getBattery().then(function(battery) { console.log(battery.level); // ... and any subsequent updates. battery.onlevelchange = function() { console.log(this.level); }; });
Alternatively, the same using the addEventListener()
method:
navigator.getBattery().then(function(battery) { console.log(battery.level); battery.addEventListener('levelchange', function() { console.log(this.level); }); });
The following example updates the indicators to show the charging state, level and time remaining in minutes:
<!DOCTYPE html> <html> <head> <title>Battery Status API Example</title> <script> window.onload = function () { function updateBatteryStatus(battery) { document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging'; document.querySelector('#level').textContent = battery.level; document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60; } navigator.getBattery().then(function(battery) { // Update the battery status initially when the promise resolves ... updateBatteryStatus(battery); // .. and for any subsequent updates. battery.onchargingchange = function () { updateBatteryStatus(battery); }; battery.onlevelchange = function () { updateBatteryStatus(battery); }; battery.ondischargingtimechange = function () { updateBatteryStatus(battery); }; }); }; </script> </head> <body> <div id="charging">(charging state unknown)</div> <div id="level">(battery level unknown)</div> <div id="dischargingTime">(discharging time unknown)</div> </body> </html>
The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team in general for their invaluable feedback based on prototype implementations. Many thanks to the people behind the System Information API and Device Orientation Event specification for the initial inspiration. Also thanks to the nice folks bringing us the Page Visibility specification, which motivated the editor of this specification to write the introduction chapter discussing some real-world high value use cases that apply equally to this specification. Special thanks to all the participants of the Device APIs Working Group and others who have sent in substantial feedback and comments, and made the Web a better place for everyone by doing so. Finally, thanks to Lukasz Olejnik, Gunes Acar, Claude Castelluccia, and Claudia Diaz for the privacy analysis of the API.