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

• networkRequired - Simple network requirement
• heavyTask - WiFi + charging for large operations
• none - No constraints (runs ASAP)

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

• BackoffPolicy - Retry behavior on failure
• QoS - iOS task priority
• ExactAlarmIOSBehavior - iOS exact alarm handling

Annotations

• @immutable

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})

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 task fails (Android only).

final

backoffPolicy → BackoffPolicy

Backoff policy when task fails and needs retry (Android only).

final

bgTaskType → BGTaskType?

iOS background task type selection (iOS 13.0+ only).

final

exactAlarmIOSBehavior → ExactAlarmIOSBehavior

iOS-specific behavior for exact time alarms.

final

foregroundServiceType → ForegroundServiceType?

Android 14+ foreground service type for heavy tasks.

final

hashCode → int

The hash code for this object.

no setter, override

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 setter, inherited

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}) → 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.