Chargeline docs
v1.0.0
Get help
● Set up

Android background logging
receiver, worker, optional service.

How Android logs charges when the app is closed, what the Play Console needs to know, and why some phones behave differently.

WorkManagerspecialUsebattery optimisation

01How it works

  • Power receiver (PowerReceiver.kt): logs plug and unplug when Android delivers the broadcast.
  • 15-minute check (WorkManager): logs anything the receiver missed. Events found this way are tagged android_worker.
  • Optional foreground service (TargetService.kt): runs only while charging and only if the user turned on the charge target alert, to log the moment the level passes the target. It shows a persistent notification while running.

Events go to a local file; the app imports it into its local SQLite database. Session rules: two plug-ins without an unplug merge, an unplug less than 90 seconds after plugging is noise, a session open more than 36 hours is marked incomplete. Times are stored in UTC.

02Phone makers and battery optimisation

Real devices differ

Android phone makers (Xiaomi, Huawei, Oppo, Samsung and others) add their own battery managers that can stop background work. Whether background logging runs reliably depends on the phone and its settings; the author did not test on real devices. Tell your users, in your own help text, to allow the app to run in the background if events are missing.

  1. Settings, Apps, your app, Battery: choose Unrestricted (the wording differs by maker).
  2. On makers with an "autostart" or "protected apps" list, allow the app.
  3. Allow notifications (Android 13+ asks for the notification permission; the charge alert needs it).
  4. Check the Live panel after one real charge; the Night Strip should show it.

Android 12 and newer may refuse to start a foreground service from the background. The app catches that, and the 15-minute check keeps logging, so the target moment can be late.

03Play Console: foreground service declaration

The manifest declares the foreground service type specialUse and permissions FOREGROUND_SERVICE and FOREGROUND_SERVICE_SPECIAL_USE. In Play Console, App content, Foreground service permissions, choose the special use type and paste a justification and a short demo video link. A text based on the code:

The app lets the user set a charge target (for example 80 %). While the phone is
charging and only if the user turned the target alert on, a foreground service
watches the battery level and records the moment the level passes the target, so
it can be shown in the user's own charging log and as a notification. The service
stops when charging stops or the user turns the alert off. No data leaves the phone.
Foreground service type: specialUse. It cannot be replaced by WorkManager because
the moment must be logged while charging, and WorkManager runs about every
15 minutes.

The same sentence is in the manifest as PROPERTY_SPECIAL_USE_FOREGROUND_SERVICE_SUBTYPE. Adjust the text to what your build really does. If you remove the service, also remove its manifest entries and permissions.