Foreground Service Health

On Android, a persistent foreground service is what keeps background location tracking alive. But asking to track (Tracelet.start()) is not the same as the OS granting a running foreground service. On Android 12+ a foreground-service start can be deferred or rejected — even while your app believes tracking is enabled.

Tracelet.getForegroundServiceHealth() closes that gap. It reports the authoritative native state of the foreground service so you can tell the difference between “tracking was requested” and “tracking is actually running” — and react when they diverge.

Why enabled isn’t enough

Tracelet.getState().enabled is the desired state — the persisted intent to track. It answers “has the app asked to track?”, not “is the OS actually running the foreground service right now?”.

Those can differ, especially on Android 12+ (API 31+), where starting a location foreground service from the background is restricted:

• The start can be deferred — Android refuses it while the app is backgrounded, and Tracelet retries automatically when the app next returns to the foreground.
• The start can fail outright — e.g. a missing permission, or a ForegroundServiceStartNotAllowedException.
• The service can be promoted, then stopped by the system.

In all of these cases enabled stays true, but background tracking is not operational. A location-timestamp watchdog can eventually notice staleness, but it can’t tell you why — whether promotion failed, the service was stopped, or the provider is simply waiting for a fresh fix. getForegroundServiceHealth() gives you the actual, authoritative reason.

The API

final health = await Tracelet.getForegroundServiceHealth();

Returns a Map<String, Object?> with the following keys:

Reading the promotion result

serviceForeground combined with lastForegroundPromotionResult tells you the whole story:

A tracking-health indicator

The most common use: surface an honest status to the user (or your telemetry) instead of blindly trusting enabled.

Future<String> describeTrackingHealth() async {
  final h = await Tracelet.getForegroundServiceHealth();
 
  if (h['desiredEnabled'] != true) return 'Tracking off';
 
  // iOS/web have no foreground service — enabled tracking is as good as it gets.
  if (h['platform'] != 'android') return 'Tracking active';
 
  if (h['serviceForeground'] == true) return 'Tracking active';
 
  switch (h['lastForegroundPromotionResult']) {
    case 'deferred':
      return 'Waiting to start — reopen the app to resume background tracking';
    case 'failed':
      final reason = h['lastForegroundPromotionFailureMessage'] ?? 'unknown';
      return 'Background tracking failed to start: $reason';
    default:
      return 'Starting…';
  }
}

A recovery watchdog

Pair the health check with a periodic timer to detect and recover from a failed promotion — for example, prompt the user to reopen the app, or re-request the missing permission.

Timer.periodic(const Duration(minutes: 1), (_) async {
  final h = await Tracelet.getForegroundServiceHealth();
 
  final desired = h['desiredEnabled'] == true;
  final foreground = h['serviceForeground'] == true;
  final result = h['lastForegroundPromotionResult'];
 
  if (desired && !foreground && result == 'failed') {
    // Background tracking is not operational. Log it, alert your backend,
    // or guide the user to fix permissions / battery settings.
    await reportTrackingDegraded(
      failureClass: h['lastForegroundPromotionFailureClass'],
      failureMessage: h['lastForegroundPromotionFailureMessage'],
    );
  }
});

Platform behavior

In Tracelet Doctor

You don’t have to build any of this yourself to see it. The tracelet_doctor overlay now includes a Foreground Service card that renders exactly this information — desired vs. actual, promotion result, and any failure class/message — with a color-coded status (Healthy / Deferred / Failed / Inactive).

tracelet_doctor is a dev dependency (flutter pub add dev:tracelet_doctor), so guard it with kDebugMode:

import 'package:flutter/foundation.dart' show kDebugMode;
import 'package:tracelet_doctor/tracelet_doctor.dart';
 
if (kDebugMode) {
  TraceletDoctor.show(context); // includes the Foreground Service card
}

The same fields are also captured in the bug report (TraceletBugReport.build()), so a pasted report shows whether the foreground service was actually running at the time of the issue — often the missing clue in “tracking stops in the background” reports.

Good to know

• Read-only & cheap. The call just reads in-memory native state; it never starts, stops, or mutates tracking.
• Safe before ready(). It returns a sensible default snapshot rather than throwing if the SDK hasn’t been initialized.
• Desired vs. actual is the whole point. Keep using getState().enabled for your app’s intent; use getForegroundServiceHealth() to verify the OS is honoring that intent.