Tutorial: Battery API - Low charge notification (JavaScript)

Battery API - Low charge notification

The web is pushing forward and with it its new possibilities. One of the newest achievements is the JavaScript Battery API which is already included (prefixed) in WebKit (Chrome, Safari) and Gecko (Firefox). This API provides information about the current charge level and allows you - via events - to notify the user e.g. about a low charge or allows the website to disable CPU intense operations. Some of you may ask yourself why do we need that? An important use case would be a business-critical (financial) app where you could notify the user about the low Battery charge and warn him that his data or transactions will be lost if he/she wouldn't charge their device.





Accessing the Battery object


In order to access the mentioned API you'll need to get the object:


var battery = navigator.battery || navigator.webkitBattery || navigator.mozBattery;

Battery attributes


The object contains four readyonly attributes:


  • charging - Boolean representation of the charge status. If the battery is charging, the state isn't determinable or the system has no battery it will return true and false if the battery is discharging.
  • chargingTime - Double representation of the remaining time to fully charge the battery in seconds. Returns positive infinity if the battery isn't charging or it isn't possible to get the remaining charging time.
  • dischargingTime - Double representation of the remaining time until the battery is discharged. Returns positive infinity if the battery is charging or it isn't possible to get the remaining discharging time or no battery is attached.
  • level - Double representation of the current charge status between 0.0 and 1.0.


Battery events


There are also four corresponding events:


  • chargingchange - When the device is started to charge or discharge
  • chargingtimechange - When the device charging time changes (plugged in)
  • dischargingtimechange - When the device discharging time changes (unplugged)
  • levelchange - When the device level changes


How to inform the user


If you want to inform the user to charge their device to prevent data loss, you could do the with the following script:



// Get the object
var battery = navigator.battery || navigator.webkitBattery || navigator.mozBattery;

// Call this function if the level of charge is under a critical value
function chargeLevelUnderCriticalValue() {
// The critical value of 5 percent
var criticalValue = 5;
// Just notify if the device isn't charged and the critical value is hit
if (!battery.charging && level <= (criticalValue / 100)) {
alert('We detected that your device has a low charge and we wanted to inform you, ' +
'that the the current operation could not be finished which could constitute data loss. ' +
'To prevent that, please charge your device. Thanks.');
}
}

// Execute function if event is fired
battery.addEventListener('levelchange', chargeLevelUnderCriticalValue);


Example


You could try the online demo.


Source: Mozilla Developer Network: mozBattery


Published by on 20. March 2012