Constraints class

Constraints that must be met before a task can run.

Constraints optimize battery life and ensure tasks run under appropriate conditions. The OS will defer task execution until all constraints are met.

Basic Examples

Network Required:

await NativeWorkManager.enqueue(
  taskId: 'api-sync',
  trigger: TaskTrigger.periodic(Duration(hours: 1)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  constraints: Constraints.networkRequired,
);

WiFi + Charging (Heavy Task):

await NativeWorkManager.enqueue(
  taskId: 'video-upload',
  trigger: TaskTrigger.oneTime(),
  worker: NativeWorker.httpUpload(
    url: 'https://cdn.example.com/videos',
    filePath: '/path/to/video.mp4',
  ),
  constraints: Constraints.heavyTask,
);

Custom Constraints:

await NativeWorkManager.enqueue(
  taskId: 'db-cleanup',
  trigger: TaskTrigger.periodic(Duration(days: 1)),
  worker: DartWorker(callbackId: 'cleanupDatabase'),
  constraints: Constraints(
    requiresDeviceIdle: true,
    requiresBatteryNotLow: true,
    requiresStorageNotLow: true,
  ),
);

Common Constraint Patterns

Data Sync (Network Required):

Constraints(requiresNetwork: true)

Large Upload (WiFi + Battery Safe):

Constraints(
  requiresUnmeteredNetwork: true,
  requiresCharging: true,
  isHeavyTask: true,
)

Maintenance Task (Device Idle):

Constraints(
  requiresDeviceIdle: true,
  requiresBatteryNotLow: true,
)

Critical Task (No Constraints):

Constraints.none // or Constraints()

Static Helpers

When to Use Constraints

✅ Use constraints for:

  • Network-dependent operations (API calls, uploads)
  • Battery-intensive tasks (video processing)
  • Storage-intensive operations (downloads, caching)
  • Maintenance work (cleanup, optimization)

❌ Don't use constraints for:

  • Time-critical operations
  • User-initiated actions (use no constraints)
  • Tasks that must run immediately

Battery Impact

More constraints = Better battery life:

  • Tasks deferred until optimal conditions
  • OS can batch work together
  • Prevents running on cellular data
  • Avoids draining battery

Platform Differences

Android:

  • All constraints enforced by WorkManager
  • Very reliable constraint checking
  • Can combine multiple constraints

iOS:

  • Constraints are advisory (not strictly enforced)
  • Best effort by BGTaskScheduler
  • Some constraints (requiresDeviceIdle) not available

See Also

Annotations

Constructors

Constraints({bool requiresNetwork = false, bool requiresUnmeteredNetwork = false, bool requiresCharging = false, bool requiresDeviceIdle = false, bool requiresBatteryNotLow = false, bool requiresStorageNotLow = false, bool allowWhileIdle = false, bool isHeavyTask = false, QoS qos = QoS.background, ExactAlarmIOSBehavior exactAlarmIOSBehavior = ExactAlarmIOSBehavior.showNotification, BackoffPolicy backoffPolicy = BackoffPolicy.exponential, int backoffDelayMs = 30000, int maxRetries = 3, Set<SystemConstraint> systemConstraints = const {}, BGTaskType? bgTaskType, ForegroundServiceType? foregroundServiceType, ForegroundNotificationConfig? foregroundNotificationConfig})
const
Constraints.fromMap(Map<String, dynamic> map)
Create from map.
factory

Properties

allowWhileIdle → bool
Allow task to run during Doze mode (Android only).
final
backoffDelayMs → int
Initial backoff delay in milliseconds when a task fails.
final
backoffPolicy → BackoffPolicy
Backoff policy when task fails and needs retry.
final
bgTaskType → BGTaskType?
iOS background task type selection (iOS 13.0+ only).
final
exactAlarmIOSBehavior → ExactAlarmIOSBehavior
iOS-specific behavior for exact time alarms.
final
foregroundNotificationConfig → ForegroundNotificationConfig?
Configuration for the Foreground Service notification (Android only).
final
foregroundServiceType → ForegroundServiceType?
Android 14+ foreground service type for heavy tasks.
final
hashCode → int
The hash code for this object.
no setteroverride
isHeavyTask → bool
Indicates this is a long-running or heavy task requiring special handling.
final
maxRetries → int
Maximum number of retry attempts when a task fails.
final
qos → QoS
Quality of Service hint for task priority (iOS only).
final
requiresBatteryNotLow → bool
Task requires battery level to not be low. (Android only)
final
requiresCharging → bool
Task requires device to be charging.
final
requiresDeviceIdle → bool
Task requires device to be idle. (Android only)
final
requiresNetwork → bool
Task requires any network connection.
final
requiresStorageNotLow → bool
Task requires storage to not be low. (Android only)
final
requiresUnmeteredNetwork → bool
Task requires unmetered (WiFi) network.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
systemConstraints → Set<SystemConstraint>
System-level constraints for task execution (Android only).
final

Methods

copyWith({bool? requiresNetwork, bool? requiresUnmeteredNetwork, bool? requiresCharging, bool? requiresDeviceIdle, bool? requiresBatteryNotLow, bool? requiresStorageNotLow, bool? allowWhileIdle, bool? isHeavyTask, QoS? qos, ExactAlarmIOSBehavior? exactAlarmIOSBehavior, BackoffPolicy? backoffPolicy, int? backoffDelayMs, int? maxRetries, Set<SystemConstraint>? systemConstraints, BGTaskType? bgTaskType, ForegroundServiceType? foregroundServiceType, ForegroundNotificationConfig? foregroundNotificationConfig}) → Constraints
Create a copy with updated values.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toMap() → Map<String, dynamic>
Convert to map for platform channel.
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
override

Constants

heavyTask → const Constraints
Preset for heavy tasks (should run on WiFi + Charging).
networkRequired → const Constraints
Preset for network-dependent tasks.
none → const Constraints
No constraints - task can run anytime.