TaskTrigger.exact constructor

const TaskTrigger.exact(
  1. DateTime scheduledTime
)

Execute at an exact time (alarm-style).

Schedules a task to run at a specific DateTime. Unlike oneTime, this attempts to execute at the EXACT specified time, like an alarm.

⚠️ Platform Limitations: Exact timing has significant limitations, especially on iOS. Consider if you really need exact timing before using.

Schedule for Specific Time

// Schedule for tomorrow at 9 AM
final tomorrow9am = DateTime.now()
    .add(Duration(days: 1))
    .copyWith(hour: 9, minute: 0, second: 0);

await NativeWorkManager.enqueue(
  taskId: 'morning-reminder',
  trigger: TaskTrigger.exact(tomorrow9am),
  worker: DartWorker(callbackId: 'sendReminder'),
);

Schedule for 2 Hours from Now

await NativeWorkManager.enqueue(
  taskId: 'delayed-notification',
  trigger: TaskTrigger.exact(
    DateTime.now().add(Duration(hours: 2)),
  ),
  worker: DartWorker(callbackId: 'showNotification'),
);

Platform Behavior & Limitations

Android (API 31+):

  • Uses AlarmManager for exact timing
  • Requires SCHEDULE_EXACT_ALARM permission (auto-granted)
  • User can revoke permission in Settings
  • Task may fail if permission revoked
  • Battery optimization may still defer task
  • Most reliable of the two platforms

iOS:

  • Severely limited - NOT recommended
  • Cannot guarantee code execution at exact time
  • Uses UNNotification as workaround
  • Requires user interaction to run code
  • Not suitable for background tasks
  • Consider using oneTime or windowed instead

When to Use

✅ Use exact trigger for (Android only):

  • Alarm clock functionality
  • Scheduled reminders
  • Time-sensitive operations
  • Exact appointment notifications

❌ Don't use exact trigger for:

  • iOS apps (very limited)
  • Background data sync (use periodic instead)
  • Flexible timing tasks (use oneTime or windowed)
  • Battery-sensitive operations

Common Pitfalls

❌ Don't rely on this for iOS (use notifications instead) ❌ Don't assume permission is always granted on Android ❌ Don't use for routine background tasks ❌ Don't forget to check if scheduledTime is in future ✅ Do check if time is in future before scheduling ✅ Do handle Android permission denial gracefully ✅ Do consider oneTime or windowed alternatives ✅ Do use local notifications for UI alerts

Alternative Solutions

For most use cases, consider these alternatives:

// Instead of exact alarm, use windowed:
TaskTrigger.windowed(
  earliest: Duration(hours: 2),
  latest: Duration(hours: 2, minutes: 15),
)

// Or use delayed oneTime:
TaskTrigger.oneTime(Duration(hours: 2))

// For UI notifications, use flutter_local_notifications:
await flutterLocalNotificationsPlugin.zonedSchedule(
  id,
  title,
  body,
  scheduledDateTime,
  notificationDetails,
);

Permission Handling (Android)

// Check if exact alarm permission is available
if (Platform.isAndroid && Build.VERSION.SDK_INT >= 31) {
  final alarmManager = AlarmManager();
  if (!await alarmManager.canScheduleExactAlarms()) {
    // Show dialog explaining need for permission
    // Direct user to settings
  }
}

See Also

  • oneTime - For flexible one-time execution
  • windowed - For execution within a time window
  • periodic - For recurring tasks

Implementation

const factory TaskTrigger.exact(DateTime scheduledTime) = ExactTrigger;