Abstract

This specification defines an API that provides information about the battery status of the hosting device.

Status of This Document

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 since the W3C Last Call Working Draft 28 August 2014 (diff).

The CR exit criterion is two interoperable deployed implementations of each feature. No features are marked as 'at-risk'.

This API uses EcmaScript promises, and as a result, relies on the second edition of WebIDL which has not yet started its path on the W3C Recommendation track. That dependency will need to be analysed before the document can make further progress.

This document was published by the Device APIs Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate 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 comments are welcome.

Please see the Working Group's implementation report.

Publication as a Candidate 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.

Table of Contents

1. Introduction

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.

2. Conformance

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 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], as this specification uses that specification and terminology.

3. Terminology

The following concepts, terms and interfaces are defined in [HTML5]:

Promise objects are defined in [ECMASCRIPT].

4. Security and privacy considerations

This section is non-normative.

The API defined in this specification is used to determine the battery status of the hosting device. The information disclosed has minimal impact on privacy or fingerprinting, and therefore is exposed without permission grants. For example, the user agent can 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.

5. The Navigator interface

partial interface Navigator {
    Promise<BatteryManager> getBattery ();
};

For each browsing context, 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:

The user agent MUST NOT reject the battery promise.

6. The BatteryManager interface

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. 

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.

Note

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 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 a simple 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 a simple 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 a simple event named levelchange at the BatteryManager object.

Note

The definition of how often the chargingtimechange, dischargingtimechange, and levelchange events are fired is left to the implementation.

6.1 Multiple batteries

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.

6.2 Event handlers

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

7. Examples

This section is non-normative.

This trivial example writes the battery level to the console each time the level changes:

Example 1
// 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:

Example 2
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:

Example 3
<!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>

A. Acknowledgements

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.

B. References

B.1 Normative references

[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL2]
Cameron McCormack. Web IDL (Second Edition). 13 November 2014. Editor’s Draft. URL: http://heycam.github.io/webidl/