Battery Status API

The Navigator interface

        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:

If the relevant settings object of this Navigator object is not a secure context, then reject this Navigator object's battery promise with a "SecurityError" DOMException, return this Navigator object's battery promise and abort these steps.
If this Navigator object's relevant global object's associated 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.
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 feature policy.
If this Navigator object's battery promise is not null, return this Navigator object's battery promise and abort these steps.
Otherwise, set this Navigator object's battery promise to a newly created Promise, created in the Realm of this Navigator object.
Return this Navigator object's battery promise and continue asynchronously.
Create a new BatteryManager object in the Realm of this Navigator object, and let battery be that object.
Resolve this Navigator object's battery promise with battery.

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.

        [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.

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.

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`

Examples

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>

Introduction

Terminology

Security and privacy considerations

The Navigator interface

The BatteryManager interface

Multiple batteries

Event handlers

Feature Policy integration

Examples

Acknowledgements