SystemConstraint enum

System-level constraints for task execution (Android only).

New in KMP WorkManager 2.2.0+: SystemConstraints provide a cleaner way to specify system-level requirements. These replace the deprecated trigger-based approach (TaskTrigger.batteryLow, etc.) and the individual boolean flags.

Platform Support: Android only. iOS ignores these constraints.

Basic Usage

await NativeWorkManager.enqueue(
  taskId: 'maintenance-task',
  trigger: TaskTrigger.oneTime(),
  worker: DartWorker(callbackId: 'cleanup'),
  constraints: Constraints(
    systemConstraints: {
      SystemConstraint.deviceIdle,  // Run when device is idle
      SystemConstraint.allowLowStorage,  // OK to run on low storage
    },
  ),
);

Constraint Types

Storage Constraints:

• allowLowStorage - Task can run even when storage is low
• Default behavior: Task waits for sufficient storage

Battery Constraints:

• allowLowBattery - Task can run even when battery is low
• requireBatteryNotLow - Task requires battery level to not be low
• Default behavior: No battery restriction

System State:

• deviceIdle - Task requires device to be idle (screen off, no user interaction)
• Use for maintenance tasks that should not impact user experience

Migration from Old API

Before (deprecated triggers):

// OLD - deprecated in v2.2.0
trigger: TaskTrigger.storageLow,  // or batteryLow, deviceIdle

After (SystemConstraints):

// NEW - recommended approach
constraints: Constraints(
  systemConstraints: {SystemConstraint.allowLowStorage},
)

Before (boolean flags):

// OLD - still works but less flexible
constraints: Constraints(
  requiresStorageNotLow: true,
  requiresBatteryNotLow: true,
  requiresDeviceIdle: true,
)

After (SystemConstraints - more explicit):

// NEW - clearer intent
constraints: Constraints(
  systemConstraints: {
    SystemConstraint.deviceIdle,
    SystemConstraint.requireBatteryNotLow,
  },
)

Common Patterns

Maintenance Task (idle device, low priority):

Constraints(
  systemConstraints: {
    SystemConstraint.deviceIdle,
    SystemConstraint.allowLowStorage,
    SystemConstraint.allowLowBattery,
  },
  qos: QoS.utility,
)

Critical Task (needs resources):

Constraints(
  systemConstraints: {
    SystemConstraint.requireBatteryNotLow,
  },
  requiresNetwork: true,
  requiresCharging: true,
)

Background Sync (opportunistic):

Constraints(
  systemConstraints: {
    SystemConstraint.allowLowBattery,  // Run even on low battery
  },
  requiresNetwork: true,
)

Platform Behavior

Android:

• Maps to WorkManager's SystemConstraint API
• Enforced by Android WorkManager
• Affects task scheduling and execution

iOS:

• Ignored (not applicable to iOS background tasks)
• iOS has different constraint system
• Use iOS-specific constraints like requiresCharging instead

Best Practices

✅ Do use SystemConstraints for explicit intent ✅ Do combine with other constraints (network, charging) ✅ Do use deviceIdle for maintenance tasks ✅ Do use allowLowStorage/allowLowBattery for non-critical tasks

❌ Don't mix old triggers with new SystemConstraints ❌ Don't expect SystemConstraints to work on iOS ❌ Don't use deviceIdle for user-initiated tasks

See also:

• Constraints - Container for all constraint types
• TaskTrigger - When tasks should execute