ISSUE-168: getBattery() vs. requestBattery() pattern
getBattery() vs. requestBattery() pattern
- State:
- PENDING REVIEW
- Product:
- Battery Status API
- Raised by:
- Frederick Hirsch
- Opened on:
- 2014-08-04
- Description:
- on behalf of Domenic Denicola <domenic@domenicdenicola.com>
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0007.html
[[
The spec says
> The user agent SHOULD NOT reject the promise returned by getBattery(). If the user agent does not want to expose the battery information to the web page, it is RECOMMENDED to not expose getBattery() or resolve the promise with an instance of BatteryManager exposing only default values.
I think there has been an increasing push to make APIs use a requestAccessToX().then(gotAccess, didntGetAccess) style. Alex, CC'ed, has some reasons why this is a good pattern in general; if I recall they are around how it enables a better permissions model for apps. (I hope he can explain better.)
But just from a consistency point of view, it would make more sense to me to converge.
I realize that the default values idea might have been a result of a previous discussion that I missed, and would be happy to be pointed toward it. The "not expose getBattery()" part is kind of funny, as the spec is RECOMMENDing that implementations not comply with the spec :P
]]
- Related Actions Items:
ACTION-710 on Anssi Kostiainen to Look at issue-168 http://www.w3.org/2009/dap/track/issues/168 - due 2014-08-14, closed- Related emails:
- [minutes] draft minutes from DAP 2014-08-21 call (from w3c@fjhirsch.com on 2014-08-21)
- [admin] Agenda - DAP Distributed Meeting 21 August 2014 (from w3c@fjhirsch.com on 2014-08-19)
- Re: DAP-ISSUE-169: Battery API needs to be more event driven and async, less device centric. [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-11)
- Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-11)
- dap commit: Use MUST in getBattery() prose (addresses ISSUE-168). (from cvsmail@w3.org on 2014-08-11)
- RE: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from domenic@domenicdenicola.com on 2014-08-08)
- Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from mounir@lamouri.fr on 2014-08-08)
- Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-08)
- draft minutes from today's teleconference, 7 Aug 2014 (from w3c@fjhirsch.com on 2014-08-07)
- [admin] Agenda - DAP Distributed Meeting 7 August 2014 (from w3c@fjhirsch.com on 2014-08-04)
- [battery] Battery Issue summary and status (from w3c@fjhirsch.com on 2014-08-04)
- DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from sysbot+tracker@w3.org on 2014-08-04)
Related notes:
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0009.html
[[
The Battery Status API doesn't require user permission to access the
battery:
https://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html#security-and-privacy-considerations
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0011.html
[[
> The Battery Status API doesn't require user permission to access the battery: https://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html#security-and-privacy-considerations
Right; in general we are pretty much done with infobar-style permission asks, as a platform. But we can still use the requestAccessToX().then(gotAccess, didntGetAccess) style even if getting access is not done as the result of an infobar. Perhaps you get access if you declare the need in a manifest, or if you're transported over HTTPS, or you get it by default but the user can toggle it off on a per-webpage basis. The user-facing API can still be uniform.
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0021.html
[[
I agree, .requestWhatever() doesn't imply an info bar. Uniformity across APIs is good here. We are looking to use this pattern also in the Screen Wake Lock API.
--
Marcos Caceres
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0031.html
[[
> basis. The user-facing API can still be uniform.
I don't think the requestFoo() model works very well for battery. The
API is defined in a way that if you did not get access to the battery
for the reasons listed above, we still RECOMMEND getBattery() to return
a BatteryManager with default values.
-- Mounir
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0032.html
[[
> I don't think the requestFoo() model works very well for battery. The API is defined in a way that if you did not get access to the battery for the reasons listed above, we still RECOMMEND getBattery() to return a BatteryManager with default values.
Yes, I guess I was not clear. My original post was mainly about questioning whether this is a good recommendation, instead of forcing authors to handle the failure path. Thus "I realize that the default values idea might have been a result of a previous discussion that I missed, and would be happy to be pointed toward it." The name is not the important part; indeed for back-compat and reduced churn I might imagine we want to keep getBattery().
All that said, it's still worrying that the spec has RECOMMENDations instead of MUSTs for what seems like a key requirement for interop. Whichever is decided---default dummy battery, or failure path---IMO the spec should mandate one (and certainly not RECOMMEND omitting getBattery entirely).
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0033.html
[[
I made a small editorial tweak to clarify this:
https://dvcs.w3.org/hg/dap/rev/cb5bbd14501b
Thanks,
-Anssi
]]
http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0035.html
[[
> All that said, it's still worrying that the spec has RECOMMENDations
> instead of MUSTs for what seems like a key requirement for interop.
> Whichever is decided---default dummy battery, or failure path---IMO the
> spec should mandate one (and certainly not RECOMMEND omitting getBattery
> entirely).
The reasons were various. One is convenience. When the property was
synchronously accessible, having to check if navigator containing the
field battery could have been tiring. Another issue that this mitigates
is fingerprinting: whether you use a desktop, a fully charged laptop or
the UA doesn't want to reveal the battery information, the author will
get the same values. That mitigate the fingerprinting as much as we can
without having to go trough a permission prompt hell.
That's the approach we took when we designed this API, quite a long time
ago. Time has past and some concerns might no longer applied or be
considered as important as they used to.
-- Mounir
]]
Resolved with:
https://dvcs.w3.org/hg/dap/rev/6cb6dc26210d
Display change log