Copyright © 2016 W3C ® ( MIT , ERCIM , Keio , Beihang ). 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/.
No
substantial
changes
have
A
minor
but
substantive
change
has
been
made
to
the
Battery
Status
API
since
the
W3C
Candidate
Proposed
Recommendation
of
December
2014
(
diff
)
,
however
March
2016
(diff),
with
the
document
now
has
more
detailed
privacy
considerations,
including
advice
regarding
association
of
the
implications
Battery
Manager
promise
to
the
Navigator
object
rather
than
the
browsing
context.
In
addition,
concerns
about
possible
privacy-invasive
usage
of
high
precision
readouts,
based
on
feedback
from
implementation
experience
.
It
also
has
updated
references.
the
Battery
Status
API
have
been
raised,
which
the
Working
Group
intends
to
review
to
determine
if
additional
mitigation
strategies
are
needed.
This
specification
is
thus
returning
to
Candidate
Recommendation
status.
The
implementation
report
of
the
API
shows
all
features
have
been
implemented
by
two
independent
deployed
browsers,
meeting
the
primary
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
criteria,
so
the
Battery
Status
API;
Working
Group
intends
to
proceed
to
Proposed
Recommendation
once
the
interoperability
effect
of
that
issue
is
minimal,
since
it
only
affects
error
handling
in
case
where
substantive
change
and
the
API
is
mis-used,
which
is
in
practice
detected
at
development
time
rather
privacy
concerns
have
been
sufficiently
reviewed,
no
sooner
than
usage
time.
01
September
2016.
This
document
was
published
by
the
Device
APIs
Working
Group
as
a
Proposed
Candidate
Recommendation.
This
document
is
intended
to
become
a
W3C
Recommendation.
The
W3C
Membership
and
other
interested
parties
are
invited
If
you
wish
to
review
the
document
and
send
make
comments
regarding
this
document,
please
send
them
to
public-device-apis@w3.org
(
subscribe
,
archives
)
through
29
April
2016.
Advisory
Committee
Representatives
should
consult
their
WBS
questionnaires
.
Note
that
substantive
technical
comments
were
expected
during
the
Last
Call
review
period
).
W3C
publishes
a
Candidate
Recommendation
to
indicate
that
ended
02
October
2014.
Please
see
the
Working
Group's
document
is
believed
to
be
stable
and
to
encourage
implementation
report
.
by
the
developer
community.
This
Candidate
Recommendation
is
expected
to
advance
to
Proposed
Recommendation
no
earlier
than
01
September
2016.
All
comments
are
welcome.
Publication
as
a
Proposed
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
1
September
2015
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 [ WEBIDL ], as this specification uses that specification and terminology.
The following concepts, terms and interfaces are defined in [ HTML5 ] and [ ECMASCRIPT ]:
Navigator
EventHandler
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 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.
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.
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
updateBatteryStatus
navigator.getBattery().then(function(battery) {
// Update the battery status initially when the promise resolves ...
updateBatteryStatus(battery);
battery
updateBatteryStatus
// .. and for any subsequent updates.
battery.onchargingchange = function () {
updateBatteryStatus(battery);
};
battery
updateBatteryStatus
battery.onlevelchange = function () {
updateBatteryStatus(battery);
};
battery
updateBatteryStatus
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.