This
specification
defines
an
API
that
provides
information
about
the
battery
status
of
the
hosting
device.
Status
of
This
Document
This
is
a
preview
Do
not
attempt
to
implement
this
version
of
the
specification.
Do
not
reference
this
version
as
authoritative
in
any
way.
Instead,
see
https://w3c.github.io/battery/
for
the
Editor's
draft.
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
https://www.w3.org/TR/.
No
substantial
changes
have
been
made
to
the
Battery
Status
API
since
the
W3C
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
implementation
report
of
the
API
shows
all
features
have
been
implemented
by
two
independent
deployed
browsers,
meeting
the
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
the
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.
Publication
as
an
Editor's
Draft
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.
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.
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
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.
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
created
in
the
relevant
settings
object
of
this
Navigator
object
object's
relevant
realm
.
There
is
not
also
a
secure
context
,
then
reject
this
Navigator
object's
battery
promise
with
a
"
manager
,
which
is
initially
null.
SecurityError
"
Warning
DOMException
This
method
is
not
currently
restricted
to
a
secure
context
,
return
this
but
it
should
be.
Track
progress
on
that
in
issue
#15
.
The
Navigator
getBattery
()
object's
battery
promise
and
abort
these
steps.
method
steps
are:
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.
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
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.
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.
// 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:
<!DOCTYPE html><html><head><title>Battery Status API Example</title><script>window.onload = function () {
functionupdateBatteryStatus(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><divid="charging">(charging state unknown)</div><divid="level">(battery level unknown)</div><divid="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.
Finally,
thanks
to
Lukasz
Olejnik,
Gunes
Acar,
Claude
Castelluccia,
and
Claudia
Diaz
for
the
privacy
analysis
of
the
API.