auto_start_flutter는 Android 및 iOS 플랫폼에서 백그라운드 실행 권한을 관리하는 데 도움을 주는 Flutter 플러그인입니다. 이 플러그인은 안드로이드 기기(미아오, 삼성 등)의 자동 시작 설정에 액세스할 수 있게 해주며, iOS의 백그라운드 앱 새로 고침도 지원합니다. 패키지는 플랫폼별 권한 요청 및 구성 처리를 단순화하여 일관된 백그라운드 동작을 보장합니다. 푸시 알림, 위치 추적 또는 주기적인 데이터 싱크와 같은 백그라운드 작업이 필요한 앱에 적합합니다. 플러그인은 Flutter 프로젝트에 원활하게 통합되며, macOS, Windows, Linux를 포함한 여러 플랫폼을 지원합니다.
사용 사례
iOS에서 백그라운드 앱 새로 고침 사용
안드로이드에서 자동 시작 권한 부여
백그라운드 작업 실행 지원
기기별 전력 절약 설정 관리
신뢰할 수 있는 푸시 알림 전달 보장
주요 기능
크로스 플랫폼 백그라운드 권한 관리
안드로이드 자동 시작 설정 지원 (샤오미 등)
iOS 백그라운드 앱 리프레시 통합
플랫폼에 관계없는 API 설계
다중 플랫폼 지원 (Android, iOS, macOS, Windows, Linux)
적합한 대상
지속적인 백그라운드 실행이 필요한 앱
엄격한 전력 관리가 적용된 Android OEM을 대상으로 하는 개발자
신뢰할 수 있는 푸시 알림이 필요한 프로젝트
크로스 플랫폼 모바일 애플리케이션
백그라운드 위치 또는 데이터 동기화를 사용하는 앱
고려 사항
Android 및 iOS에서 사용자 권한이 필요합니다
특정 OEM에 대해 추가 구성이 필요할 수 있습니다
운영체제 정책에 의해 백그라운드 실행이 제한됨
모든 기기에서 동일한 백그라운드 동작을 지원하지는 않습니다
사용자는 시스템 설정에서 권한을 수동으로 활성화해야 할 수 있습니다
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
auto_start_flutter
A Flutter plugin to help manage background execution permissions on Android, iOS, macOS, Windows, and Linux devices. It supports requesting "Auto-Start" permissions on specific Android OEM devices, checking "Background App Refresh" status on iOS, and managing "Startup Apps / Login Items" settings on Windows and macOS to ensure your app can run reliably in the background.
Features
Auto-Start Permission:
Android: Open manufacturer-specific "Auto-Start" or "App Launch" settings.
iOS: Check Background App Refresh status.
Windows/macOS: Open the "Startup Apps" or "Login Items" system settings.
Battery Optimization: Check if the app is exempt from battery optimizations and open settings to request exemption (Android) or power settings (Windows/macOS).
Device Support:
Android: Xiaomi, Redmi, Poco, Oppo, Vivo, Huawei, Honor, Samsung, ASUS, OnePlus, Nokia, LeTV, Meizu, HTC, Infinix, and more.
iOS: All devices.
Windows: Windows 10/11.
macOS: macOS 10.14+ (limitations apply).
Linux: Supported (stubbed methods due to varying Desktop Environments).
Robustness: The plugin attempts multiple known intents for each manufacturer to ensure the settings page opens correctly.
On Android, this checks if the device is from a manufacturer known to have aggressive auto-start restrictions and redirects the user to the appropriate settings page.
On iOS, this checks if Background App Refresh is enabled. If not, it redirects the user to the App Settings page where they can enable it.
On Windows and macOS, this opens the Startup Apps or Login Items system settings, where users can toggle your app's startup status.
import'package:auto_start_flutter/auto_start_flutter.dart';
// ...// 1. Check if auto-start permission is available / relevant// Android: Returns true for Xiaomi, Oppo, Vivo, etc.// iOS: Returns true if Background App Refresh is available (not restricted).var isAvailable = await isAutoStartAvailable;
if (isAvailable == true) {
// 2. Request permission / Open Settings// Android: Opens Auto Start settings or App Info.// iOS: Opens App Settings.// Windows/macOS: Opens Startup Apps / Login Items settings.awaitgetAutoStartPermission();
}
Other Features
App Info: Open the system settings page for the app.
String? manufacturer = awaitgetDeviceManufacturer();
// e.g. "Xiaomi", "Apple", "Samsung"
Custom Settings (Android Only): If you know the specific package and activity name for a setting page on a specific device, you can attempt to open it directly.
// Example: Try opening a specific hidden settingawaitopenCustomSetting(
packageName: 'com.android.settings',
activityName: 'com.android.settings.Settings\$PowerUsageSummaryActivity',
);
Background Execution & Boot
The plugin provides advanced lifecycle hooks to natively launch your app in the background across platforms.
Boot Completed Trigger (registerBootCallback): Run a headless Dart callback or launch your app the moment the device turns on.
Android: Uses the BOOT_COMPLETED intent and spawns a secure background FlutterEngine.
Windows: Natively writes the executable path with an --autostart flag directly into the HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry.
macOS: Uses the modern Apple SMAppService.mainApp.register() API to register the application into Login Items seamlessly (macOS 13+).
Linux: Generates a standardized X-GNOME .desktop file natively inside ~/.config/autostart/.
import'dart:ui';
import'package:flutter/material.dart';
// 1. Must be a top-level or static function@pragma('vm:entry-point')
voidmyBootCallback() {
WidgetsFlutterBinding.ensureInitialized();
print("Device booted! Running in the background...");
}
// 2. Register it somewhere in your app (e.g. main.dart)awaitregisterBootCallback(myBootCallback);
Note: On Android, you must manually add the RECEIVE_BOOT_COMPLETED permission to your AndroidManifest.xml (see Mandatory Setup below).
Foreground Service Keep-Alive (Android): Start a foreground service to prevent Android from killing your app when it goes to the background. This will pin a persistent notification to the user's status bar.
// Start the serviceawaitstartForegroundService(
title: "Syncing Data",
content: "Do not close the app.",
);
// Stop the service when doneawaitstopForegroundService();
Note: On Android, you must manually add the FOREGROUND_SERVICE permission to your AndroidManifest.xml (see Mandatory Setup below).
Exact Scheduling & Alarms (scheduleTask): Schedule a task to run precisely at a future timestamp.
Android: Uses AlarmManager for highly accurate background wakes, triggering a headless Dart callback even in Doze mode.
iOS & macOS: Apple strictly prohibits generic headless background wakes at exact times. Therefore, this API relies on UNUserNotificationCenter. It will schedule a Local Notification for the exact timestamp. When the user taps the notification, the app opens, and getLaunchArguments will contain the taskId and callbackHandle. This will prompt the user for Notification Permissions the first time it is called.
Windows: Natively interfaces with the Windows Task Scheduler COM API.
Linux: Automatically manages systemd user timers.
final at = DateTime.now().add(Duration(minutes: 5));
bool success = awaitscheduleTask(at, myScheduledTaskCallback, taskId: "my_task_1");
// On app startup, check if we were launched by a scheduled taskfinal args = awaitgetLaunchArguments();
if (args['scheduledTaskId'] == 'my_task_1') {
print("Woke up from scheduled task!");
}
Exact Alarm Permissions (Android 12+ / API 31+):
Starting in Android 12, apps scheduling exact alarms must verify permission:
// Check if exact alarms can be scheduledbool canSchedule = awaitcanScheduleExactAlarms();
if (!canSchedule) {
// Guide user to the system "Alarms & reminders" settings pageawaitopenExactAlarmSettings();
}
Headless Execution (executeInBackground) (Phase 3): Execute a Dart callback immediately in the background without bringing the app to the foreground or attaching a UI.
Android/Apple: Instantiates a dedicated headless FlutterEngine / Isolate.
Desktop (Windows/Linux): Spawns a hidden background process via the native executable.
// 1. Must be a top-level or static function@pragma('vm:entry-point')
voidmyHeadlessTask() {
WidgetsFlutterBinding.ensureInitialized();
print("Running in the background instantly!");
}
// 2. Trigger executionawaitexecuteInBackground(myHeadlessTask);
Android's Doze mode and App Standby can restrict background processing. On Windows and macOS, energy/power settings can similarly affect background performance.
Check Status: Check if your app is already ignoring battery optimizations.
Open Battery Optimization Settings (Recommended & Google Play Safe):
Navigates the user to the standard system battery optimization list (ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS on Android). This does not require declaring high-risk permissions or justifying policies in Google Play Console.
if (!isExempt) {
awaitopenBatteryOptimizationSettings();
}
Direct Dialog Exemption (Requires Policy Declaration):
On Android 6.0+, prompts the user directly via a system dialog using ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS.
[!WARNING]
Google Play strictly limits apps requesting direct battery exemption dialogs. Only use disableBatteryOptimization() if your app qualifies under Google Play exemption policies. Otherwise, use openBatteryOptimizationSettings().
if (!isExempt) {
awaitdisableBatteryOptimization();
}
Platform Support
Platform
Supported
Notes
Android
✅
Supports custom OEM intents and standard battery optimization settings.
iOS
✅
Checks UIBackgroundRefreshStatus and opens App Settings.
Windows
✅
Opens Startup Apps settings.
macOS
✅
Opens Login Items settings.
Linux
✅
Basic support. Most methods return logical defaults as DE APIs vary wildly.
Note: Standard Android APIs do not allow checking if "Auto Start" is actually enabled. isAutoStartAvailable only returns true if the device manufacturer is on the supported list (e.g. Xiaomi, Oppo). On Windows and macOS, isAutoStartAvailable returns true to indicate that the "Startup Apps" / "Login Items" setting is accessible. Only iOS allows verifying the actual background refresh status programmatically.
Mandatory Setup (Android)
To keep the plugin lightweight and privacy-focused, permissions are no longer included by default. You must add the permissions required for the features you intend to use to your android/app/src/main/AndroidManifest.xml.
Note: If you use openBatteryOptimizationSettings(), no special permission is required in your AndroidManifest.xml!
5. Headless Execution (Phase 3)
No special permissions are strictly required for executeInBackground to spin up the background isolate. However, if your headless task requires internet access or long-running CPU locks, ensure standard Flutter network permissions or battery optimization exemptions are handled.
Contributing
If you find any issues or would like to add support for more devices, please file an issue or pull request on GitHub.