foreground_background_manager #

A production-ready Flutter plugin for:

• 🔄 App lifecycle detection (foreground / background / paused / detached)
• 🚀 Android Foreground Service — persists through minimize, background, AND app kill
• ⏰ Background task scheduling (WorkManager on Android, BGTaskScheduler on iOS)
• 🔔 Permissions handling (notifications, battery optimization)
• 🔁 Auto-restart after app kill and device reboot

How "Always Running" Works #

Three layers ensure the service survives every kill scenario:

Setup #

Android AndroidManifest.xml #

Add inside <manifest>:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

Add inside <application>:

<service
    android:name="com.example.foreground_background_manager.FBMForegroundService"
    android:exported="false"
    android:foregroundServiceType="dataSync"
    android:stopWithTask="false" />

<receiver
    android:name="com.example.foreground_background_manager.FBMBootReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.intent.action.QUICKBOOT_POWERON" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>

iOS Info.plist #

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.yourapp.sync_task</string>
</array>

Quick Start #

// 1. Top-level callback dispatcher (MUST be top-level)
@pragma('vm:entry-point')
void callbackDispatcher() {
  ForegroundBackgroundManager.backgroundCallbackDispatcher();
}

// 2. Background task callback (MUST be top-level)
@pragma('vm:entry-point')
Future<void> mySync() async {
  print('Syncing in background...');
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await ForegroundBackgroundManager.initialize(
    callbackDispatcher: callbackDispatcher,
  );

  runApp(const MyApp());
}

Start a Kill-Proof Foreground Service #

// Step 1: Request battery optimization ignore (IMPORTANT for OEMs)
await ForegroundBackgroundManager.permissions.requestIgnoreBatteryOptimization();

// Step 2: Request notification permission (Android 13+)
await ForegroundBackgroundManager.permissions.requestNotificationPermission();

// Step 3: Start service
await ForegroundBackgroundManager.startForegroundService(
  title: 'App Running',
  content: 'Service active — survives app kill',
  autoRestart: true, // ← this enables auto-restart
);

// Stop
await ForegroundBackgroundManager.stopForegroundService();

Lifecycle Streams #

ForegroundBackgroundManager.lifecycleStream.listen((state) {
  print(state.label); // "Foreground (Resumed)", "Background (Paused)", etc.
});

ForegroundBackgroundManager.onForeground.listen((_) => print('→ Foreground'));
ForegroundBackgroundManager.onBackground.listen((_) => print('→ Background'));
ForegroundBackgroundManager.onAppKilled.listen((_) => print('→ Killed!'));

Background Tasks #

await ForegroundBackgroundManager.registerBackgroundTask(
  taskId: 'sync_task',
  interval: const Duration(minutes: 15), // minimum on both platforms
  callback: mySync,
);

OEM-Specific Notes #

Platform Limitations #

iOS:

• No foreground service — startForegroundService is a no-op.
• BGTask execution is OS-controlled; minimum interval ~15 min; may be delayed.
• Force-quit by user cancels all pending BGTasks.

Android:

• WorkManager minimum repeat interval: 15 minutes.
• SCHEDULE_EXACT_ALARM may need user grant on Android 12+.
• On Android 14+, foregroundServiceType must be declared.