apsl_wallpaper_scheduler

A Flutter package for scheduling automatic daily wallpaper updates on Android.

Download an image from any URL and set it as the Home Screen, Lock Screen, or Both at an exact time every day — even when the app is closed or the device reboots.

Android only. iOS does not expose a public API for setting wallpapers programmatically.

Features

Schedule multiple independent wallpaper updates at different times
Targets: Home Screen, Lock Screen, or Both
Uses Android's setExactAndAllowWhileIdle — truly exact timing (not the inexact setRepeating)
Survives app kill and device reboots (rescheduleOnReboot: true)
Stores all schedules in SharedPreferences — persists across launches
Shows a local notification after each successful update
Full CRUD: create, read, update, delete, start, stop
Permission checks return plain booleans — your app controls all dialogs

Platform Support

Android	iOS
✅ API 21+	❌ Not supported

Installation

Add to your pubspec.yaml:

dependencies:
  apsl_wallpaper_scheduler: ^0.2.2

Android Setup

1. `android/app/src/main/AndroidManifest.xml`

Add inside <manifest>:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.SET_WALLPAPER"/>
<uses-permission android:name="android.permission.SET_WALLPAPER_HINTS"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>
<uses-permission android:name="android.permission.USE_EXACT_ALARM"/>
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS"/>

Add inside <application>:

<service
    android:name="dev.fluttercommunity.plus.androidalarmmanager.AlarmService"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:exported="false"/>
<receiver
    android:name="dev.fluttercommunity.plus.androidalarmmanager.AlarmBroadcastReceiver"
    android:exported="false"/>
<receiver
    android:name="dev.fluttercommunity.plus.androidalarmmanager.RebootBroadcastReceiver"
    android:enabled="false"
    android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
    </intent-filter>
</receiver>

2. `android/app/build.gradle.kts`

Enable core library desugaring (required by flutter_local_notifications):

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    defaultConfig {
        minSdk = 21   // minimum required
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

Usage

Initialize (once in `main()`)

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await ApslWallpaperScheduler.initialize();
  runApp(const MyApp());
}

Permissions

The package checks permissions internally and surfaces the results as plain booleans. Your app is fully responsible for showing dialogs — the package never shows UI of its own.

Two permissions are required for reliable alarm delivery:

Permission	Why needed
`SCHEDULE_EXACT_ALARM`	Android 12+ requires explicit permission for exact alarms.
Battery optimisation exemption	Without it, aggressive OEM battery savers (Samsung, Xiaomi, OnePlus, Realme…) kill background alarms even when the alarm permission is granted.

Proactive check — show dialogs before scheduling

The recommended pattern: check what is missing at app start, show your own rationale dialogs, then request each permission.

Future<void> _ensurePermissions(BuildContext context) async {
  final perms = await ApslWallpaperScheduler.checkPermissions();

  if (!perms.hasExactAlarm) {
    // Show YOUR rationale dialog first
    final proceed = await showDialog<bool>(
      context: context,
      builder: (_) => AlertDialog(
        title: const Text('Alarm permission needed'),
        content: const Text(
          'To update your wallpaper at the exact time you chose, '
          'this app needs the "Alarms & Reminders" permission.',
        ),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context, false),
            child: const Text('Not now'),
          ),
          ElevatedButton(
            onPressed: () => Navigator.pop(context, true),
            child: const Text('Allow'),
          ),
        ],
      ),
    );
    if (proceed == true) {
      await ApslWallpaperScheduler.requestExactAlarmPermission();
    }
  }

  if (!perms.hasBatteryExemption) {
    // Show YOUR rationale dialog first
    final proceed = await showDialog<bool>(
      context: context,
      builder: (_) => AlertDialog(
        title: const Text('Background activity needed'),
        content: const Text(
          'To keep wallpapers updating while the app is closed, '
          'please disable battery optimisation for this app.',
        ),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context, false),
            child: const Text('Skip'),
          ),
          ElevatedButton(
            onPressed: () => Navigator.pop(context, true),
            child: const Text('Allow'),
          ),
        ],
      ),
    );
    if (proceed == true) {
      final granted = await ApslWallpaperScheduler.requestBatteryOptimizationExemption();
      // granted == true  → exemption was allowed
      // granted == false → user declined; alarms may be suppressed on some OEMs
    }
  }
}

Reactive check — handle denied permissions from a result

Every scheduling method (createSchedule, updateSchedule, startSchedule) returns a ScheduleResult. When the failure is caused by a missing permission, result.requiredPermissions is non-null so you can react without a separate checkPermissions() call.

final result = await ApslWallpaperScheduler.createSchedule(config);

if (!result.isSuccess) {
  final perms = result.requiredPermissions;

  if (perms != null) {
    // Permission-related failure — ask the user to grant what is missing.
    if (!perms.hasExactAlarm) {
      final proceed = await showDialog<bool>(
        context: context,
        builder: (_) => AlertDialog(
          title: const Text('Alarm permission denied'),
          content: const Text(
            'The schedule could not be activated because the '
            '"Alarms & Reminders" permission is not granted.\n\n'
            'Open Settings → Apps → [Your App] → Alarms & Reminders '
            'and enable it, then try again.',
          ),
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(context, false),
              child: const Text('Cancel'),
            ),
            ElevatedButton(
              onPressed: () => Navigator.pop(context, true),
              child: const Text('Open Settings'),
            ),
          ],
        ),
      );
      if (proceed == true) {
        await ApslWallpaperScheduler.requestExactAlarmPermission();
      }
    }

    if (!perms.hasBatteryExemption) {
      final proceed = await showDialog<bool>(
        context: context,
        builder: (_) => AlertDialog(
          title: const Text('Battery optimisation active'),
          content: const Text(
            'The alarm may be suppressed by the battery saver on your device.\n\n'
            'Tap Allow to disable battery optimisation for this app so '
            'wallpapers update reliably in the background.',
          ),
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(context, false),
              child: const Text('Skip'),
            ),
            ElevatedButton(
              onPressed: () => Navigator.pop(context, true),
              child: const Text('Allow'),
            ),
          ],
        ),
      );
      if (proceed == true) {
        final granted = await ApslWallpaperScheduler.requestBatteryOptimizationExemption();
        // granted == false → user declined; warn them alarms may be unreliable
      }
    }
  } else {
    // Non-permission failure (e.g. network error in a different context)
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(result.error ?? 'Unknown error')),
    );
  }
}

Permission status at a glance

final perms = await ApslWallpaperScheduler.checkPermissions();

print(perms.hasExactAlarm);      // true / false
print(perms.hasBatteryExemption); // true / false
print(perms.isFullyGranted);     // true only when both are granted

Schedule Operations

Create a schedule

final result = await ApslWallpaperScheduler.createSchedule(
  WallpaperScheduleConfig(
    name: 'Morning Wallpaper',
    imageUrl: 'https://example.com/morning.png',
    time: const TimeOfDay(hour: 8, minute: 0),
    target: WallpaperTarget.both,      // homeScreen | lockScreen | both
    activate: true,                     // schedule alarm immediately (default)
  ),
);

if (result.isSuccess) {
  print('Created: ${result.schedule!.id}');
} else {
  print('Error: ${result.error}');
  // Check result.requiredPermissions — see Permissions section above
}

Get all schedules

final schedules = await ApslWallpaperScheduler.getAllSchedules();
for (final s in schedules) {
  print('${s.name}  ${s.formattedTime}  active=${s.isActive}');
}

Get a single schedule

final schedule = await ApslWallpaperScheduler.getSchedule(id);

Get only active schedules

final active = await ApslWallpaperScheduler.getActiveSchedules();

Update a schedule

final result = await ApslWallpaperScheduler.updateSchedule(
  id: existingScheduleId,
  config: WallpaperScheduleConfig(
    name: 'Updated Name',
    imageUrl: 'https://example.com/new_image.png',
    time: const TimeOfDay(hour: 9, minute: 30),
    target: WallpaperTarget.homeScreen,
    activate: true,
  ),
);

Stop a schedule (keep but deactivate)

await ApslWallpaperScheduler.stopSchedule(scheduleId);

Start a stopped schedule

final result = await ApslWallpaperScheduler.startSchedule(scheduleId);
// result.requiredPermissions is non-null if it failed due to permissions

Delete a schedule

await ApslWallpaperScheduler.deleteSchedule(scheduleId);

Delete all schedules

await ApslWallpaperScheduler.deleteAllSchedules();

API Reference