forked from w3c/battery
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
519 lines (515 loc) · 21.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
<!DOCTYPE html>
<html>
<head>
<title>
Battery Status API
</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class=
'remove'>
</script>
<script class="remove">
var respecConfig = {
specStatus: "ED",
shortName: "battery-status",
//publishDate: "2016-03-29",
previousPublishDate: "2014-12-09",
previousMaturity: "CR",
edDraftURI: "https://w3c.github.io/battery/",
lcEnd: "2014-10-02",
prEnd: "2016-04-29",
editors: [
{ name: "Anssi Kostiainen", company: "Intel", companyURL: "http://intel.com/" },
{ name: "Mounir Lamouri", company: "Google Inc.", companyURL: "https://google.com/", note: "previously Mozilla" }
],
inlineCSS: true,
noIDLIn: true,
noLegacyStyle: true,
wg: "Device and Sensors Working Group",
wgURI: "https://www.w3.org/2009/dap/",
wgPublicList: "public-device-apis",
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/43696/status",
testSuiteURI: "http://w3c-test.org/battery-status/",
implementationReportURI: "https://w3c.github.io/test-results/battery-status/20160621.html",
scheme: "https",
processVersion: 2005
};
</script>
</head>
<body>
<section id="abstract">
This specification defines an API that provides information about the
battery status of the hosting device.
</section>
<section id="sotd">
<p>
No substantial changes have been made to the Battery Status API since
the <a href=
"https://www.w3.org/TR/2014/CR-battery-status-20141209/">W3C Candidate
Recommendation</a> of December 2014 (<a href="PR-diff.html">diff</a>) ,
however the document now has more detailed privacy considerations,
including advice regarding the implications of high precision readouts,
based on feedback from <a href=
"https://lists.w3.org/Archives/Public/public-device-apis/2015Aug/0000.html">
implementation experience</a>. It also has updated references.
</p>
<p>
The <a href=
"https://w3c.github.io/test-results/battery-status/20160226.html">implementation
report</a> 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'.
</p>
<p>
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.
</p>
</section>
<section class="informative">
<h2>
Introduction
</h2>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section id="conformance">
<p>
This specification defines conformance criteria that apply to a single
product: the <dfn>user agent</dfn> that implements the interfaces that
it contains.
</p>
<p>
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.
</p>
</section>
<section>
<h2>
Terminology
</h2>
<p>
The following concepts, terms and interfaces are defined in [[!HTML5]]
and [[!ECMASCRIPT]]:
</p>
<ul>
<li>
<code><a href=
"https://www.w3.org/TR/html5/webappapis.html#navigator"><dfn>Navigator</dfn></a></code>
</li>
<li>
<code><a href=
"https://www.w3.org/TR/html5/webappapis.html#eventhandler">EventHandler</a></code>
</li>
<li>
<dfn><a href=
"https://www.w3.org/TR/html5/webappapis.html#queue-a-task">queue a
task</a></dfn>
</li>
<li>
<dfn><a href=
"https://www.w3.org/TR/html5/webappapis.html#fire-a-simple-event">fires
a simple event</a></dfn>
</li>
<li>
<dfn><a href=
"https://www.w3.org/TR/html5/webappapis.html#event-handlers">event
handlers</a></dfn>
</li>
<li>
<dfn><a href=
"https://www.w3.org/TR/html5/webappapis.html#event-handler-event-type">
event handler event types</a></dfn>
</li>
<li>
<a href=
"https://tc39.github.io/ecma262/#sec-promise-objects"><dfn>Promise</dfn></a>
</li>
<li>
<a href="https://tc39.github.io/ecma262/#realm"><dfn data-lt=
"realm">Realms</dfn></a>
</li>
</ul>
</section>
<section class="informative">
<h2>
Security and privacy considerations
</h2>
<p>
The API defined in this specification is used to determine the battery
status of the hosting device.
</p>
<p>
The user agent SHOULD not expose high precision readouts of battery
status information as that can introduce a new fingerprinting vector.
</p>
<p>
The user agent MAY ask the user for battery status information access,
or alternatively, enforce the user permission requirement in its
private browsing modes.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section>
<h2>
The <a>Navigator</a> interface
</h2>
<pre class="idl">
partial interface Navigator {
Promise<BatteryManager> getBattery();
};
</pre>
<p>
For each <a>Navigator</a> object, there is a <dfn>battery
promise</dfn>, which is initially set to <code>null</code>. It is a
<a>Promise</a> object which holds a <a>BatteryManager</a>.
</p>
<p>
The <code id=
"widl-Navigator-getBattery-Promise-BatteryManager">getBattery()</code>
method, when invoked, MUST run the following steps:
</p>
<ol>
<li>If this <a>Navigator</a> object's <a>battery promise</a> is not
<code>null</code>, return this <a>Navigator</a> object's <a>battery
promise</a> and abort these steps.
</li>
<li>Otherwise, set this <a>Navigator</a> object's <a>battery
promise</a> to a newly created <a>Promise</a>, created in the
<a>Realm</a> of this <a>Navigator</a> object.
</li>
<li>Return this <a>Navigator</a> object's <a>battery promise</a> and
continue asynchronously.
</li>
<li>
<a>Create a new <code>BatteryManager</code> object</a> in the
<a>Realm</a> of this <a>Navigator</a> object, and let
<var>battery</var> be that object.
</li>
<li>Resolve this <a>Navigator</a> object's <a>battery promise</a> with
<var>battery</var>.
</li>
</ol>
<p>
The <a>user agent</a> MUST NOT reject the <a>battery promise</a>.
</p>
</section>
<section>
<h2>
The <a>BatteryManager</a> interface
</h2>
<p>
The <a>BatteryManager</a> interface represents the <dfn>current battery
status information</dfn> of the hosting device. The
<code>charging</code> attribute represents the charging state of the
system's battery. The <code>chargingTime</code> attribute represents
the time remaining in seconds until the system's battery is fully
charged. The <code>dischargingTime</code> 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
<code>level</code> attribute represents the level of the system's
battery.
</p>
<pre class="idl">
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;
};
</pre>
<p>
When the <a>user agent</a> is to <dfn>create a new
<code>BatteryManager</code> object</dfn>, it MUST instantiate a new
<a>BatteryManager</a> object and set its attributes' values to those
that represent the <a>current battery status information</a>, unless
the <a>user agent</a> is <a>unable to report the battery status
information</a>, in which case the values MUST be set to <dfn>default
values</dfn> as follows: <code>charging</code> MUST be set to true,
<code>chargingTime</code> MUST be set to 0,
<code>dischargingTime</code> MUST be set to positive Infinity, and
<code>level</code> MUST be set to 1.0.
</p>
<p>
The <a>user agent</a> is said to be <dfn>unable to report the battery
status information</dfn>, 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.
</p>
<p class="note">
Implementations <a>unable to report the battery status information</a>
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.
</p>
<p>
The <code id="widl-BatteryManager-charging">charging</code> 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 <a>user agent</a> MUST
<a>queue a task</a> which sets the <code>charging</code> attribute's
value and <a>fires a simple event</a> named
<code><a>chargingchange</a></code> at the <a>BatteryManager</a> object.
</p>
<p>
The <code id="widl-BatteryManager-chargingTime">chargingTime</code>
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 <a>user agent</a> MUST <a>queue a task</a> which sets
the <code>chargingTime</code> attribute's value and <a>fires a simple
event</a> named <code><a>chargingtimechange</a></code> at the
<a>BatteryManager</a> object.
</p>
<p>
The <code id=
"widl-BatteryManager-dischargingTime">dischargingTime</code> 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 <a>user agent</a> MUST
<a>queue a task</a> which sets the <code>dischargingTime</code>
attribute's value and <a>fires a simple event</a> named
<code><a>dischargingtimechange</a></code> at the <a>BatteryManager</a>
object.
</p>
<p>
The <code id="widl-BatteryManager-level">level</code> 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 <a>user agent</a>
MUST <a>queue a task</a> which sets the <code>level</code> attribute's
value and <a>fires a simple event</a> named
<code><a>levelchange</a></code> at the <a>BatteryManager</a> object.
</p>
<p class="note">
The definition of how often the <code><a>chargingtimechange</a></code>,
<code><a>dischargingtimechange</a></code>, and
<code><a>levelchange</a></code> events are fired is left to the
implementation.
</p>
<section id="multiple-batteries">
<h2>
Multiple batteries
</h2>
<p>
If a hosting device contains more than one battery,
<a>BatteryManager</a> SHOULD expose an unified view of the batteries.
</p>
<p>
The <code>charging</code> attribute MUST be set to true if at least
one battery's <code>charging</code> state as described above is true.
Otherwise, it MUST be set to false.
</p>
<p>
The <code>chargingTime</code> 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.
</p>
<p>
The <code>dischargingTime</code> 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.
</p>
<p>
The <code>level</code> 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.
</p>
</section>
<section>
<h2>
Event handlers
</h2>
<p>
The following are the <a>event handlers</a> (and their corresponding
<a>event handler event types</a>) that MUST be supported as
attributes by the <a>BatteryManager</a> object:
</p>
<table class="simple">
<thead>
<tr>
<th>
event handler
</th>
<th>
event handler event type
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<strong><code id=
"widl-BatteryManager-onchargingchange">onchargingchange</code></strong>
</td>
<td>
<code><dfn>chargingchange</dfn></code>
</td>
</tr>
<tr>
<td>
<strong><code id=
"widl-BatteryManager-onchargingtimechange">onchargingtimechange</code></strong>
</td>
<td>
<code><dfn>chargingtimechange</dfn></code>
</td>
</tr>
<tr>
<td>
<strong><code id=
"widl-BatteryManager-ondischargingtimechange">ondischargingtimechange</code></strong>
</td>
<td>
<code><dfn>dischargingtimechange</dfn></code>
</td>
</tr>
<tr>
<td>
<strong><code id=
"widl-BatteryManager-onlevelchange">onlevelchange</code></strong>
</td>
<td>
<code><dfn>levelchange</dfn></code>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<section class="informative">
<h2>
Examples
</h2>
<p>
This trivial example writes the battery level to the console each time
the level changes:
</p>
<pre class="example highlight">
// 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);
};
});
</pre>
<p>
Alternatively, the same using the <code>addEventListener()</code>
method:
</p>
<pre class="example highlight">
navigator.getBattery().then(function(battery) {
console.log(battery.level);
battery.addEventListener('levelchange', function() {
console.log(this.level);
});
});
</pre>
<p>
The following example updates the indicators to show the charging
state, level and time remaining in minutes:
</p>
<pre class="example highlight">
<!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>
</pre>
</section>
<section class="appendix">
<h2>
Acknowledgements
</h2>
<p>
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.
</p>
</section>
</body>
</html>