Android SDK: Taming the Battery Manager

Android is infamous for aggressively killing background services. Chinese OEMs (like Xiaomi, Huawei) even have custom power managers that completely break standard Android background execution limits.

This page explains why Android kills your app and how Tracelet’s specific Android configurations solve it in the real world.

Optional dependency: high-accuracy GMS location

Tracelet’s Android SDK can use Google Play Services Location — FusedLocationProviderClient (better accuracy and battery), hardware activity recognition (walking / driving / still), and hardware geofencing. To keep the SDK lightweight and usable on Google-less devices, this dependency is not bundled. You add it only if you want the high-accuracy path:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.gms:play-services-location:21.3.0")
}

Optional dependency: Play Integrity (device attestation)

If you use Tracelet’s device attestation feature (AttestationConfig), the Android side generates its cryptographic token through Google Play Integrity. Just like play-services-location, this dependency is not bundled — you add it only when you enable attestation:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.play:integrity:1.6.0")
}

Permissions & Manifest Setup

Tracelet automatically injects the necessary permissions into your AndroidManifest.xml when you compile your app. By default, it requests:

• ACCESS_COARSE_LOCATION & ACCESS_FINE_LOCATION (Required for tracking)
• ACCESS_BACKGROUND_LOCATION (Required for tracking when app is closed)
• FOREGROUND_SERVICE & FOREGROUND_SERVICE_LOCATION (Required for continuous background execution)
• ACTIVITY_RECOGNITION (Required for the smart motion-detection engine)
• POST_NOTIFICATIONS (Required for Android 13+ foreground service UI)
• SCHEDULE_EXACT_ALARM (Required for precise Periodic Mode tracking)

Removing Unused Permissions (Manifest Merger)

If your app doesn’t need a specific feature (for example, your client doesn’t need motion detection, or you don’t use Periodic Mode), you can forcefully remove the permission using Android’s manifest merger tools:node="remove" directive in your app-level AndroidManifest.xml (android/app/src/main/AndroidManifest.xml).

Tracelet’s native code is fully guarded with checkSelfPermission(). Missing permissions will trigger graceful fallbacks, not crashes.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
 
    <!-- Geofence-only / periodic-only app: no continuous foreground tracking -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" tools:node="remove" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" tools:node="remove" />
 
</manifest>

Example: Removing Motion & Background Permissions

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
 
    <!-- Client doesn't want Activity/Motion tracking -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" tools:node="remove" />
    
    <!-- Client only wants foreground tracking -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" tools:node="remove" />
 
    <!-- Remove Exact Alarms -->
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" tools:node="remove" />
    
</manifest>

Automatic ProGuard / R8 Rules

Tracelet heavily utilizes background Kotlin services, JNA bindings for the Rust core, and reflective Pigeon channels. If these are obfuscated or shrunk incorrectly, background tracking will silently fail when your app is compiled for release.

You do not need to manually configure ProGuard for Tracelet.

The tracelet_android plugin automatically ships with embedded consumer-rules.pro. When you build your Flutter app in release mode, Android’s R8 shrinker automatically extracts these rules and ensures all necessary classes (such as the HeadlessTaskService, BootReceiver, and the Rust uniffi bindings) survive shrinking.

Scenario 1: The Delivery Driver (Continuous Tracking)

Concepts Explored: Doze Mode, Foreground Services, Wakelocks

The Problem

Your user is a pizza delivery driver. They put the phone in their pocket, turning off the screen. After 15 minutes, Android enters Doze Mode. It shuts down network access, defers background jobs, and severely limits CPU wake-ups to save battery. If your app relies on a simple timer to get GPS, Android will simply refuse to run your timer.

How Tracelet Solves It: Foreground Service

A Foreground Service tells Android: “Hey, I am doing something incredibly important right now, and the user is fully aware of it. Do not kill me.”

android: tl.AndroidConfig(
  foregroundService: tl.ForegroundServiceConfig(
    enabled: true,
    channelName: 'Delivery Tracking',
    notificationText: 'Tracking your route to the customer',
    notificationOngoing: true, // User cannot swipe it away
    showNotificationOnPauseOnly: false, // Auto-hides when app is open
    actions: ['Pause', 'Complete'], // Adds interactive buttons to the notification
  ),
)

By showing a persistent notification in the status bar, Tracelet elevates your app’s priority to almost the level of the foreground UI. Android will let Tracelet run indefinitely, bypassing Doze Mode restrictions.

Customizing the Notification Appearance

To make the persistent notification match your app’s branding, you can customize the icons and colors:

android: tl.AndroidConfig(
  foregroundService: tl.ForegroundServiceConfig(
    enabled: true,
    notificationTitle: 'Delivery Mode',
    notificationText: 'Tracking your route...',
    notificationColor: '#0F9D58', // Your brand hex color
    notificationSmallIcon: 'ic_tracelet_icon', // The icon name
    notificationLargeIcon: 'ic_large_logo',
  ),
)

Important Icon Rules:

1. File Location: The image file must be placed in your Android project’s drawable folder (android/app/src/main/res/drawable/ic_tracelet_icon.png).
2. Small Icon Constraints: Android requires the notificationSmallIcon to be completely flat, transparent, and white-only. If you use a colored logo, Android will simply render it as a solid gray or white square.
3. Color Property: The notificationColor property will tint the background of your small icon to match your brand.

Refreshing the Notification While Tracking (updateNotification())

Need to change the notification after tracking has already started — e.g. update the title from “En route” to “Arriving”, swap the text, or change the action buttons mid-trip? Calling setConfig() with a new ForegroundServiceConfig persists the values, but a notification-only change does not repost the notification that Android is already showing — the new content would only appear after an unrelated service restart or foreground transition.

Since v3.6.8, Tracelet.updateNotification() refreshes the live notification in place, without restarting the tracking pipeline:

// 1. Apply the new notification content.
await Tracelet.setConfig(
  const tl.Config(
    android: tl.AndroidConfig(
      foregroundService: tl.ForegroundServiceConfig(
        notificationTitle: 'Arriving',
        notificationText: 'Your driver is 2 minutes away',
      ),
    ),
  ),
);
 
// 2. Repost the active notification with the new content.
await Tracelet.updateNotification();

Scenario 2: The Weather App (Periodic Tracking)

Concepts Explored: WorkManager vs. Exact Alarms

The Problem

Your user downloaded your local weather app. You want to wake up in the background once every 4 hours, get their location, and download the local forecast.

You do not want a persistent Foreground Service notification. The user would hate seeing a permanent “Weather tracking” notification in their drawer.

How Tracelet Solves It: Periodic Mode

Instead of a continuous service, Tracelet can use Android’s job schedulers to wake up briefly, get a fix, and go back to sleep.

android: tl.AndroidConfig(
  periodicUseForegroundService: false, 
  periodicUseExactAlarms: true, // Uses AlarmManager instead of WorkManager
)

The Two Schedulers

1. WorkManager (periodicUseExactAlarms: false) The default. It is very battery friendly. However, Android decides when to run it. If you ask it to run every 15 minutes, Android might wait 45 minutes and run it when the user unlocks their phone to check Instagram (called “batching”). It is highly inexact.

2. AlarmManager (periodicUseExactAlarms: true) If you absolutely MUST wake the device up exactly at a specific time, use this. It requires you to declare the SCHEDULE_EXACT_ALARM permission in your android/app/src/main/AndroidManifest.xml:

   <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

   Note: Google Play strictly reviews this permission. Only use it if your app is an alarm clock, calendar, or absolutely requires exact timing.

Scenario 3: The OEM Aggression

Concepts Explored: Settings Health API

The Problem

You did everything right. You have a Foreground Service. But the user owns a Xiaomi phone. MIUI has a proprietary “Battery Saver” that force-kills even Foreground Services after 5 minutes of screen-off time.

How Tracelet Solves It: Auto-Mitigation and Prompts

Tracelet automatically applies internal mitigations where possible, but sometimes the user physically has to whitelist your app in the OEM’s proprietary settings menu.

final health = await tl.Tracelet.getSettingsHealth();
if (health['isAggressiveOem'] == true) {
  // Automatically opens the manufacturer-specific settings screen 
  // (e.g. Xiaomi Autostart, Huawei App Launch, Samsung Sleeping Apps)
  await tl.Tracelet.showPowerManager();
}

For a detailed example of how to implement this in your Flutter UI, see the Diagnostic Tools & Power Management page.