Battery Status API

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2022/WD-battery-status-20220203/
Latest published version:
https://www.w3.org/TR/battery-status/
Latest editor's draft:
https://w3c.github.io/battery/
History:
https://www.w3.org/standards/history/battery-status
Commit history
Test suite:
https://wpt.live/battery-status/
Implementation report:
https://w3c.github.io/test-results/battery-status/20160621.html
Editors:
Anssi Kostiainen (Intel Corporation)
Mounir Lamouri (Google Inc.) (previously Mozilla)
Raphael Kubo da Costa (Intel Corporation)
Feedback:
GitHub w3c/battery (pull requests, new issue, open issues)
public-device-apis@w3.org with subject line [battery-status] … message topic … (archives)

Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

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. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The Devices and Sensors Working Group will apply editorial modernizations to this specification, perform a round of self-review and revisions on the security and privacy aspects of the API before requesting horizontal review. Existing security and privacy issues are available.

This document was published by the Devices and Sensors Working Group as a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

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 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 2 November 2021 W3C Process Document.

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 MAY, MUST, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

3. Security and privacy considerations

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.

4. Concepts

The task source for the tasks mentioned in this specification is the battery status task source.

5. Extensions to the Navigator interface 

WebIDL[SecureContext]
partial interface Navigator {
  Promise<BatteryManager> getBattery();
};
Note

This method was exposed to a non-secure context until PR #51.

5.1 Internal slots

Internal slot Initial value Description
[[BatteryPromise]] null A Promise returned by calls to getBattery().
[[BatteryManager]] null The BatteryManager instance associated with a given Navigator after it has been created via getBattery().

5.2 The getBattery() method

The getBattery() method steps are:

  1. If this.[[BatteryPromise]] is null, then set it to a new promise in this's relevant realm.
  2. If this's relevant global object's associated Document is not allowed to use the "battery" policy-controlled feature, then reject this.[[BatteryPromise]] with a "NotAllowedError" DOMException.
    Note
    In other words, this step rejects if the associated 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 permissions policy.
  3. Otherwise:
    1. If this.[[BatteryManager]] is null, then set it to the result of creating a new BatteryManager in this's relevant realm.
    2. Resolve this.[[BatteryPromise]] with this.[[BatteryManager]].
  4. Return this.[[BatteryPromise]].

6. The BatteryManager interface 

WebIDL[SecureContext, 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;
};

The BatteryManager interface represents the current battery status information of the hosting device.

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

6.1 Internal slots

BatteryManager instances are created with the following internal slots:

Internal slot Initial value
[[Charging]] true
[[ChargingTime]] 0
[[DischargingTime]] Positive Infinity
[[Level]] 1.0

6.1.1 The [[Charging]] internal slot

The [[Charging]] internal slot represents the charging state of the system's battery. It 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 system battery's charging state changes, the user agent must run the update the battery status and notify algorithm with [[Charging]], true or false depending on whether the battery is charging or discharging, and "chargingchange".

6.1.2 The [[ChargingTime]] internal slot

The [[ChargingTime]] internal slot represents the remaining time in seconds until the system's battery is fully charged. It 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 run the update the battery status and notify algorithm with [[ChargingTime]], the new charging time in seconds, and "chargingtimechange".

6.1.3 The [[DischargingTime]] internal slot

The [[DischargingTime]] attribute represents the remaining time in seconds until the system's battery is completely discharged and the system is about to be suspended. It 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 run the update the battery status and notify algorithm with [[DischargingTime]], the new discharging time in seconds, and "dischargingtimechange".

6.1.4 The [[Level]] internal slot

The [[Level]] internal slot represents the system's battery's level. It 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 run the update the battery status and notify algorithm with [[Level]], the new battery level, and "levelchange".

Note

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

6.2 The charging attribute

The charging getter steps are to return this.[[Charging]].

6.3 The chargingTime attribute

The chargingTime getter steps are to return this.[[ChargingTime]].

6.4 The dischargingTime attribute

The dischargingTime getter steps are to return this.[[DischargingTime]].

6.5 The level attribute

The level getter steps are to return this.[[Level]].

6.6 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

6.7 Algorithms

To update the battery status and notify given an internal slot slot, a value and an eventName, run the following steps:

  1. Let global be the current global object.
  2. If global is not a Window, abort these steps.
  3. Let navigator be global's associated Navigator.
  4. Let batteryManager be the value of navigator. [[BatteryManager]].
  5. If batteryManager is null, abort these steps.
  6. Queue a global task on the battery status task source given global to run the following steps:
    1. Set batteryManager.slot to value.
    2. Fire an event named eventName at batteryManager.

6.8 Multiple batteries

If a hosting device contains more than one battery, BatteryManager SHOULD expose a unified view of the batteries.

The [[Charging]] internal slot 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]] internal slot 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]] internal slot 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]] internal slot can be set to the average of the levels of batteries of same capacity, or the weighted average of the battery levels for batteries of different capacities.

7. Permissions Policy integration

The Battery Status API is a policy-controlled feature identified by the string "battery". Its default allowlist is 'self'.

8. 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. Index

A.1 Terms defined by this specification

A.2 Terms defined by reference

B. IDL Index

WebIDL[SecureContext]
partial interface Navigator {
  Promise<BatteryManager> getBattery();
};

[SecureContext, 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;
};

C. 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. Finally, thanks to Lukasz Olejnik, Gunes Acar, Claude Castelluccia, and Claudia Diaz for the privacy analysis of the API.

D. References

D.1 Normative references

[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[permissions-policy]
Permissions Policy. Ian Clelland. W3C. 16 July 2020. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[WEBIDL]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/