Copyright
© 2014 2016
W3C ® ( MIT , ERCIM
, Keio , Beihang ), All
Rights Reserved. ). W3C liability
, trademark
and document
use rules apply.
This specification defines an API that provides information about the battery status of the hosting device.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
The functionality described in this
specification was initially specified as part of the System
Information API but has been extracted in order to be more readily
available, more straightforward to implement, and in order to
produce a specification that could be implemented on its own merits
without interference with other, often unrelated, features.
No substantial changes have been made to the
Battery Status API since the
W3C Last Call Working Draft 28 August
2014 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 CR exit criterion is
implementation report of the API
shows all features have been implemented by two interoperable independent deployed implementations of each feature. No browsers, meeting the CR exit criteria. We had no
CR features are marked as
'at-risk'.
This API uses EcmaScript promises, and
as There is a result, relies on the second edition of
known issue with some WebIDL
which has implementations that are not yet started its path on the W3C Recommendation track.
That dependency will need specific to be analysed
before the document can make further
progress. 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.
This document was published by the Device APIs Working Group as a
Candidate Proposed Recommendation. This document is intended
to become a W3C
Recommendation. If you wish The W3C
Membership and other interested parties are
invited to make comments regarding this
document, please review the document
and send them comments to public-device-apis@w3.org (
subscribe
, archives
). W3C publishes a Candidate Recommendation
to indicate ) through 29 April 2016.
Advisory Committee Representatives should consult their
WBS questionnaires .Note that the document is
believed to be stable and to encourage implementation by the
developer community. This Candidate Recommendation is expected to
advance to Proposed Recommendation no earlier than 03 February
2015. All substantive technical
comments are welcome. were expected during the Last Call review period that
ended 02 October 2014.
Please see the Working Group's implementation report .
Publication as a Candidate
Proposed Recommendation does not imply
endorsement by the W3C Membership. This is a draft
document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as
other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 14 October 2005 W3C Process Document .
This section is non-normative.
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.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , and SHOULD are to be interpreted as described in [ RFC2119 ].
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 [ WEBIDL2 WEBIDL ], as this specification uses
that specification and terminology.
The following concepts, terms and interfaces are defined in [ HTML5 ]:
Navigator
EventHandler
Promise objects are defined in [ ECMASCRIPT ].
This section is non-normative.
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 disclosed has
minimal impact on privacy as that can
introduce a new fingerprinting vector.
The user agent MAY ask the user for battery status information
access, or fingerprinting, and
therefore is exposed without alternatively, enforce the user permission
grants. For example, 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 can 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.
BatteryManager
interfaceThe 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.
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 a simple event named
at the chargingchange
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 a simple event named
at the chargingtimechange
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 a simple event named
at the dischargingtimechange
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 a simple event named
at the
levelchange
BatteryManager
object.
The definition of how often the
, chargingtimechange
, and
dischargingtimechange
events are
fired is left to the implementation.levelchange
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 |
This section is non-normative.
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.