Cordova - Battery Status

Cordova - Battery Status

This Cordova plugin allows your application to monitor the device’s battery status. The plugin fires events when the battery level changes or when the device is plugged or unplugged.

Step 1 - Installing the Battery Status Plugin

To add the Battery Status plugin to your project, open your terminal or command prompt, navigate to your Cordova project’s root directory, and run the following command:

your-cordova-project/ cordova plugin add cordova-plugin-battery-status

Step 2 - Add Event Listener

After the plugin is installed, you need to listen for battery status events. This is typically done within the onDeviceReady function in your www/js/index.js file, ensuring the Cordova APIs are available.

// Inside the onDeviceReady function in www/js/index.js
window.addEventListener("batterystatus", onBatteryStatus, false);

Step 3 - Create Callback Function

Next, define the onBatteryStatus callback function. This function will be executed whenever a batterystatus event occurs. It receives a status object containing information about the battery.

function onBatteryStatus(status) {
    console.log("Battery Level: " + status.level + "%" + " Is Plugged: " + status.isPlugged);
    // For demonstration, we'll use alert. In a real app, update the UI.
    alert("Battery Level: " + status.level + "%\nIs Plugged: " + status.isPlugged);
}

When you run the app, this function will be triggered upon changes in battery status. For example, if the battery is 100% charged and unplugged, an alert might display: “Battery Level: 100% Is Plugged: false”.

If the battery level drops to 99%, a new alert will show: “Battery Level: 99% Is Plugged: false”.

If you then plug the device into a charger, the alert will update to something like: “Battery Level: 99% Is Plugged: true”.

Additional Events

This plugin also provides two other specific events: batterylow and batterycritical. These events fire when the battery charge percentage reaches low and critical thresholds, respectively. These thresholds are platform-dependent.

Event Name	Description
batterylow	Fires when the battery charge percentage reaches a low threshold. This value varies by device and platform.
batterycritical	Fires when the battery charge percentage reaches a critical threshold. This value also varies by device and platform.

You can listen to these events similarly to batterystatus:

window.addEventListener("batterylow", onBatteryLow, false);
window.addEventListener("batterycritical", onBatteryCritical, false);

function onBatteryLow(status) {
    alert("Battery Level Low: " + status.level + "%");
}

function onBatteryCritical(status) {
    alert("Battery Level Critical: " + status.level + "%");
}

Practical Application

In a real-world application, you could use the battery status information to:

• Notify the user to save their work when the battery is low.
• Disable battery-intensive features to conserve power.
• Adjust app behavior based on whether the device is charging (e.g., allow larger downloads only when plugged in).