Add an explicit use cases and requirements section

[anssiko]

We should consider consolidating the use cases into its own section. Some of the use cases are discussed in the introduction, some in separate GitHub issues, some can be found from the group’s mailing list discussions.

[anssiko]

I came across a use case I haven't seen discussed yet so dropping a pointer here:

My organization is using this API for a kiosk application with around 40 to 50 million users a year. Within kiosk there is no way to see the battery life so this is a necessity to avoid batteries dying without knowing it.

via https://bugs.chromium.org/p/chromium/issues/detail?id=661792#c38

[anssiko]

More use cases:

• on low power, a video playing site could switch to a less resource-intensive video codec/lower resolution
• on low power, games could reduce their frame rate or turn off optional features (maybe not every NPC needs full-power AI, for example)
• on low power, a well-behaved publisher could tell advertisers not to send video ads, only still ads
• on low power, a document, video, or image processing web app could simplify certain features, such as turn down ML-powered grammar checking, simplify video/image previews, reduce transparency/complex visual effects in the UI, et c.
• on low power, a publisher could switch layouts from expensive, radio-burning, and reflow-heavy (washingtonpost.com) to something more simple, like text.npr.org

via https://bugs.chromium.org/p/chromium/issues/detail?id=661792#c49

[anssiko]

Migrating recent use case contributions from WG participants to this issue to keep us focused and on the topic:

@anssiko said:

One new use case that have come up in the context of WebNN API, also not documented in this spec yet, is to figure out whether to download a potentially very big model for on-device inference or use a cloud-based inference instead, or some other mechanism. In this case, knowing something about the device's battery level, and whether the device is plugged in or not is helpful. "You're about to download a 2 GB model file, but it appears you're not plugged in and your battery level appears to be pretty low. Would you still want to proceed?" Not a prompt I'd propose in a product, but for illustration. Also for long-running inference tasks it is helpful to know the rough impact on your battery over a long period or time and fine-tune accordingly. This is a specific case of the general case discussed in the introduction.

@reillyeon said:

I would definitely appreciate sites like the Android Flash Tool providing a warning if you are about to try flashing a device when your battery is low.

Thanks, this Android Flash Tool is certainly a reasonable use case.

Anssi, given this API has been available for a number of years are you aware of any compelling examples of real-world use? Metrics from Chrome say ~10% of page loads call this API, what are they using it for?

I see a variety of normal household names from e-commerce, news, social, weather, education.

I observe long-tail web developers (hope that's an appropriate term!) are often more eager to share their use cases than typical big companies.

(Referring also to the Energy Saver Mode explainer here, this work was motivated by web developer use case feedback from #9.)

[anssiko]

Per Akamai's comment on blink-dev their Boomerang library uses the Battery Status API:

Boomerang is an open source JavaScript library for real user monitoring (commonly called RUM). It measures the performance characteristics of real-world page loads and interactions.

[tomayac]

Boomerang is an open source JavaScript library for real user monitoring (commonly called RUM). It measures the performance characteristics of real-world page loads and interactions.

That's an interesting use case actually. Enabling battery saver mode implies lower CPU clock speed on some devices. (This could be cross-referenced with the Compute Pressure API.)

[reillyeon]

As far as I can tell Boomerang is not directly modifying site behavior based on battery level. It is one of many metrics which are returned to the developer. We'd have to find out from developers whether this signal has been useful for designing updates to their site.

[anssiko]

I did a quick Google search and found out also other libraries and frameworks depend on this API, for example Vue, React Native and Expo.

This might provide a partial explanation to why ~10% of page loads call this API. I'm not very familiar with these libraries, but I observe Vue has ~5M weekly downloads, React Native has ~1.9M weekly downloads and Expo ~600k weekly downloads.

[tomayac]

• Allow different preset for video quality based on power source ([Feature Request] Allow diffrent preset for video quality based on power source #103  code-charity/youtube#2292)
• System monitoring in a browser extension (https://github.com/pd4d10/system-monitor/blob/59985b8167c52eb5b85d8f4c8f11d6f510c8517c/src/popup.tsx#L92)
• Emulators like for Windows 11 (https://github.com/blueedgetechno/win11React/blob/a4540200a3172f2106afdbe88322873c3497e4a8/src/components/shared/Battery.jsx#L28)

With more digging, you can probably find other non-tracking examples based on a GitHub code search…

[anssiko]

Here are a few real-world examples from open-source projects that use the Battery Status API, grouped into categories:

• App frameworks: major Vue, React Native and Expo, purpose-built Shiny, ftools, SolidJS, Ember.js plugin, Vercel component, another Vercel component, React Template, AppPresser, Open Bank Project Sofit Container, GoPro ForgeJS, Blazor
• Productivity/utils: Nylas Mail, Battery Tracker historical data viz, notifications at critical thresholds considering estimated time remaining, Edge ML browser-based toolchain for machine learning on microcontrollers, Battery Monitor remind via notifications if battery below/above user-defined thresholds, Battery Status notifies the user when it's time to plug in or unplug the laptop to maximize the battery life, Battery display, System Info Viewer
• Emulators: Win11, Win12, Ubuntu, Web3OS, Portfolio OS, RetroArch SNES/GB/Sega, Win7
  • Note: Fullscreen API spoofing attack could be made more convincing when combined with the Battery Status API.
• Development: Nutria emulate various web-based OSes, Pantomath Slack webhooks, ws-vs-xhr compare the power consumption of websockets and XMLHttpRequests in web apps, sw-periodic-sync register tasks to be run in a service worker at periodic intervals triggered battery changes, battery-considerate-loading for resources, mdsh static site generator
• Browser extensions: Auto Tab Discard discarding is skipped if power is plugged-in, Minimo, Simple New Tab Page, Chrome Newtab for battery information at a glance, ChromeOS Battery trigger custom notifications, fullscreen warning at custom battery levels, System Monitor
• Education: HAX
• Smart home: Homebridge Browsercam, Home Assistant browser control to create home automations based on the battery status
• Messaging: Franz run computationally intensive tasks only when the system is plugged in, Web-Talkie a Push-to-Talk web app
• Identity management: IDM Wallet UI adapt desktop/laptop experience based on charging status
• Cloud gaming: Better xCloud
• Performance monitoring: Boomerang is an open source JavaScript library for real user monitoring (commonly called RUM), it measures the performance characteristics of real-world page loads and interactions, The Great Suspender and The Great-er Discarder-er suspends work based on charging state
• Media: YouTube / Code Charity / Battery Considerate Loading (source) select the most appropriate codec, show a static image instead of video autoplay depending on battery level and discharging time estimate, switch to a less power-hungry codec or remind the user up front to plug in if the movieRuntime > dischargingTime, h264ify let user choose to use an energy-efficient codec when plugged in
• Automation: Scrapoxy
• Sports: Badminton Umpire Panel scoreboard to display badminton scores and warn if the device is running low battery or is unplugged, also Advantage Scout a scouting system, oled-bike-computer
• Other: Mine4aCause a nonprofit organization that creates and manages a tool to engage with the communities of non-profit organizations where members harnesses their excess browser CPU capacity to mine crypto-currency

I believe there are many projects built on top popular Vue/React Native/Expo app frameworks that make use of this API. These are however not as easily discoverable as the frameworks themselves.

[marcoscaceres]

Don't forget you also need to balance these against all the abuse cases seen at:
https://chromestatus.com/metrics/feature/timeline/popularity/2198

Like, the working group needs to answer why so many porn sites, link farms, etc. are using the API and actually look at the misuse.

Is the misuse higher then the legitimate use?

I'll also note that citing "Vue has ~5M weekly downloads, React Native has ~1.9M weekly downloads and Expo ~600k weekly downloads." That's a false equivalence.

That's like saying me saying "my blog gets billions of views a month because lots of people download web browsers." (which is simply not true). Just because someone downloads a framework, doesn't mean they are using the battery API.

I recommend a great book called "How to lie with statistics", which I recommend reading (so to avoid accidentally lying with statistics).

There may be great use cases here, but those need to be balanced also with all the abuse cases.

Also, with each use case that is found, those need to then be balanced with other ways of doing the same thing on the platform. It maybe be that you can "do X if you have the battery API", but you could also "do X" if you don't have the battery API and handle things in some other way.

So the general ask is always to consider for each case, "is this the best way meet some particular use case, and how would some other spec or technology help here."

[marcoscaceres]

For:

Here are a few real-world examples from open-source projects that use the Battery Status API,

For most, it doesn't actually explain how the API is being used and for what?

[marcoscaceres]

What would be amazing here is gathering these use cases and then sharing them with other relevant working groups for discussion (e.g., with Media WG etc.).

Otherwise it feels like you are trying to justify the existence of the battery API, instead of fully exploring how other parts of the platform could or are already addressing a lot of the use cases (particularly anything to do with fetching, media, etc.). The DAS working group may be lacking expertise in these areas, so it's best to coordinate with other groups if possible.

There are also cases where, for instance, computational work could be marked as critical, but it can be left up to the UA to inform the user when the battery is low... my Mac already does this, and so does my iPhone. Android also warns me if battery is getting critical. So those cases need to be balanced out against what the OS already provides.

There appears to be a general mindset here that sites are always trying to act in the best interest of the user (i.e., sites behaving like user agents). That's ok, but a lot of sites do not. Web sites are not user agents and can be, unfortunately, actively hostile - so it's usually best to leave "user agent" behavior, like warnings, etc. to user agents.

[anssiko]

I agree that in general it is easier to find out who use an API than figure out how the API is used. I added some descriptions to a few open-source projects in my initial list where the how part was obvious. Deployed code is often obfuscated and without comments, making it hard to figure out the how part.

I also agree this is a balancing act: mitigate known abusive use with best known methods, allow real-world use cases, keep web compatibility.

We're interested in use cases from other W3C groups and their feedback. I think code-charity/youtube#2292 is of interest to the Media WG so maybe @marcoscaceres can help discuss that use case in that group and contribute findings back to this issue. The inference use case #25 (comment) is from the WebML WG participants.

I hope we can work on this together in a productive manner.

[anssiko]

@reillyeon in the group's earlier discussion (#10 (comment)) embedded Google Maps and YouTube players were mentioned. Given these are popular embeds, I expect this may in part contribute to the wide range of top-level origins and relatively high use of this API as seen in metrics.

One of the use cases mention for YouTube was selecting the most appropriate codec. I did not find a mention of the use case for Google Maps yet.

The YouTube use case sounds similar to the use case identified by the Code Charity community in code-charity/youtube#2292 and what is demonstrated by Battery Considerate Loading (source). With these samples at hand, it appears web developers want to have a level of control over this experience. For example, in the latter case only a static image is shown if a developer-defined battery threshold is crossed, and also the resolution is chosen based on the battery status. In this same fashion, a codec could be switched to a less power-hungry or the user reminded up front to plug in if the movieRuntime > dischargingTime. It looks like web developers are creative in crafting solutions but it is quite time-consuming to unearth all the creative uses.

I updated the real-world examples list #25 (comment) accordingly.

[marcoscaceres]

Two things:

1. Please ensure that the applications are distinctly categorized as a) kiosk mode, b) browser extensions, and c) genuine web applications. It's important to recognize that kiosk modes and, in particular, browser extensions operate under security models different from those of regular web pages. As previously discussed, while it might be appropriate to expose the API in these controlled environments, suggesting that its use in a browser extension justifies broad web exposure is misleading. This is akin to claiming that old 'Cordova apps' qualify as standard implementations, when we know those are not "web applications" in the HTML sense. The concern remains that this API is, right now, primarily used as effectively spyware on the Web (even if it is useful in Kiosks and browser extensions, the sites I've looked at seem to suggest it's being used for nefarious/tracking reasons).

2. About the YouTube case (and also the browser extensions doing source selection): The selection of media based on battery status presents a valuable discussion point, but lacks sufficient consideration of varying network conditions and hardware capabilities. A more robust solution is offered by the Managed Media Source (MMS) API, which allows the browser to more effectively manage the media source. Unlike the battery-based approach, MMS API incorporates a broader spectrum of environmental factors, including available hardware and network conditions. The implementation of MMS API enhances system efficiency by reducing power consumption, improving memory management, minimizing buffer requirements, and facilitating access to 5G connectivity. Furthermore, it maintains developer control, ensuring flexibility and adaptability in media handling. Put simply, with the availability of the Managed Media Source, which was developed together with large video sites, developers don't need to the Battery API for media source selection through JS: the browser does it better/much more intelligently and efficiently - to use the Battery API would be doing their users a de service and counter productive.

[marcoscaceres]

What might also be useful is turning the use cases into a three column table: use case, examples and type (kiosk, extension, web apps), alternative solution (e.g., MMS). That would allow us see gaps. What's key here is that there may be places where the API is being used that is either ideal (a battery indicator?) or not ideal (e.g., media loading/source selection - where a better solution exists or could be standardized).

The point being that, just because someone has made some random open source project, it doesn't mean that it's necessarily the best solution or justifies the need for this API. Each project should be evaluated critically - not used to justify the existence of the API. That would be, again, a solution (the Battery API) looking for a problem (the projects).

I'd encourage you to set criteria for each project, particular:

• what's positive.
• potential harms.
• and actual examples of usage.

If you can't find actual examples of usage, then that's also somewhat telling.