@capawesome/capacitor-battery 0.0.1 → 0.1.1

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-battery
+# Capacitor Battery Plugin
 
 Capacitor plugin to access battery information.
 
@@ -10,7 +10,7 @@ Capacitor plugin to access battery information.
 
 ## Features
 
-We are proud to offer one of the most complete and feature-rich Capacitor plugins for battery information. Here are some of the key features:
+The Capacitor Battery plugin is one of the most complete battery monitoring solutions for Capacitor apps. Here are some of the key features:
 
 - 🔋 **Battery level**: Read the current battery level of the device.
 - ⚡ **Battery state**: Read whether the device is charging, full or unplugged.
@@ -18,14 +18,20 @@ We are proud to offer one of the most complete and feature-rich Capacitor plugin
 - 👂 **Change events**: Listen for changes to the battery level, state and low power mode.
 - 🌐 **Web support**: Read the battery level and state on supported browsers.
 - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
-- 🔗 **Compatibility**: Works alongside the [Android Battery Optimization](https://capawesome.io/plugins/android-battery-optimization/) plugin.
+- 🤝 **Compatibility**: Works alongside the [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/) plugin.
 - 🔁 **Up-to-date**: Always supports the latest Capacitor version.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Battery plugin is typically used whenever an app should adapt its behavior to the device's power situation, for example:
+
+- **Energy-aware features**: Reduce background work, animations, or sync frequency when the battery level is low.
+- **Low power mode handling**: Disable power-hungry features when the user has enabled low power mode.
+- **Charging-dependent tasks**: Only start heavy tasks such as large downloads while the device is charging.
+- **Status display**: Show the current battery level and charging state inside your app, for example in a kiosk or fleet app.
+- **Reacting to changes**: Warn the user when the battery level drops by listening for change events.
 
 ## Compatibility
 
@@ -65,6 +71,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to get the current battery level and state, check if low power mode is enabled, listen for battery changes, and remove all listeners.
+
+### Get the current battery level
+
+Read the current battery level of the device as a value between `0.0` and `1.0`:
+
 ```typescript
 import { Battery } from '@capawesome/capacitor-battery';
 
@@ -72,16 +84,40 @@ const getBatteryLevel = async () => {
   const { level } = await Battery.getBatteryLevel();
   return level;
 };
+```
+
+### Get the current battery state
+
+Check whether the device is charging, full or unplugged:
+
+```typescript
+import { Battery } from '@capawesome/capacitor-battery';
 
 const getBatteryState = async () => {
   const { state } = await Battery.getBatteryState();
   return state;
 };
+```
+
+### Check if low power mode is enabled
+
+Read whether the low power mode (power saver mode on Android, Low Power Mode on iOS) is currently enabled. Only available on Android and iOS:
+
+```typescript
+import { Battery } from '@capawesome/capacitor-battery';
 
 const isLowPowerModeEnabled = async () => {
   const { enabled } = await Battery.isLowPowerModeEnabled();
   return enabled;
 };
+```
+
+### Listen for battery changes
+
+Get notified when the battery level, battery state or low power mode changes. The device is only observed while at least one listener is attached. The `lowPowerModeChange` event is only available on Android and iOS:
+
+```typescript
+import { Battery } from '@capawesome/capacitor-battery';
 
 const addBatteryLevelChangeListener = async () => {
   await Battery.addListener('batteryLevelChange', event => {
@@ -100,6 +136,14 @@ const addLowPowerModeChangeListener = async () => {
     console.log('Low power mode changed:', event.enabled);
   });
 };
+```
+
+### Remove all listeners
+
+Remove all listeners that were registered for this plugin:
+
+```typescript
+import { Battery } from '@capawesome/capacitor-battery';
 
 const removeAllListeners = async () => {
   await Battery.removeAllListeners();
@@ -357,6 +401,46 @@ Keep the following platform differences in mind when accessing battery informati
 - **iOS**: The battery level is not available on the iOS Simulator, so `getBatteryLevel()` rejects with an error there. Use a real device to test this method. The low power mode reflects the [Low Power Mode](https://support.apple.com/en-us/101604) of the device.
 - **Web**: The battery level and state are only available in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers). The low power mode is not available on the Web.
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It reports the full battery picture — level, charging state, and low power mode — plus change events that observe the device only while a listener is attached, all through a fully typed API that works across Android, iOS, and supported browsers on the Web. If you just need a one-off battery reading, that's a quick call; if you want to react to charging and low-power changes over time without wasting energy, this plugin is built for exactly that.
+
+### Why does `getBatteryLevel` fail on the iOS Simulator?
+
+The battery level is not available on the iOS Simulator, so `getBatteryLevel()` rejects with an error there. Use a real device to test this method.
+
+### Does this plugin work in all browsers?
+
+No, on the Web the battery level and state are only available in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API), which are Chromium-based browsers. The low power mode is not available on the Web at all.
+
+### What is the range of the battery level value?
+
+The battery level is returned as a value between `0.0` and `1.0`, where `0.0` means the battery is empty and `1.0` means it is fully charged. Multiply the value by 100 if you want to display it as a percentage.
+
+### What does low power mode mean on Android and iOS?
+
+On Android, it refers to the [power saver mode](https://developer.android.com/reference/android/os/PowerManager#isPowerSaveMode()) of the device. On iOS, it refers to the [Low Power Mode](https://support.apple.com/en-us/101604). The `isLowPowerModeEnabled()` method and the `lowPowerModeChange` event are only available on Android and iOS.
+
+### Does listening for battery changes drain the battery?
+
+The device is only observed while at least one listener is attached. As soon as you remove all listeners, for example with `removeAllListeners()`, the plugin stops observing the device.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions on Android.
+- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, operating system, and memory.
+- [Thermal State](https://capawesome.io/docs/sdks/capacitor/thermal-state/): Read the device thermal state and react before the operating system throttles your app.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/battery/CHANGELOG.md).

package/android/build.gradle

@@ -30,7 +30,7 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-battery",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to access battery information.",
+  "version": "0.1.1",
+  "description": "Capacitor plugin to access battery information on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -33,11 +33,19 @@
       "url": "https://opencollective.com/capawesome"
     }
   ],
-  "homepage": "https://capawesome.io/docs/plugins/battery/",
+  "homepage": "https://capawesome.io/docs/sdks/capacitor/battery/",
   "keywords": [
     "capacitor",
     "plugin",
-    "native"
+    "native",
+    "capacitor-plugin",
+    "battery",
+    "battery level",
+    "battery status",
+    "battery state",
+    "low power mode",
+    "power saver",
+    "charging state"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",