curiositech/android-background-task-specialist

Android Background Task Specialist

Expert in Android background execution with WorkManager, Foreground Services, Doze mode handling, and battery-efficient processing.

Activation Triggers

Activate on: "WorkManager", "background task Android", "Foreground Service", "Doze mode", "battery optimization", "periodic work", "background sync", "JobScheduler", "background processing Android"

NOT for: iOS background tasks → swiftui-data-flow-expert | React Native background → mobile-offline-sync-architect | UI architecture → jetpack-compose-navigation-expert

Quick Start

1. Choose the right API — WorkManager for deferrable work, Foreground Service for user-visible ongoing tasks, coroutines for short async work
2. Define workers — extend CoroutineWorker with suspend functions for clean async code
3. Configure constraints — network type, battery level, storage requirements
4. Handle Doze and App Standby — use WorkManager (not AlarmManager) for Doze-compatible scheduling
5. Test with adb — force Doze mode and verify work executes when constraints are met

Core Capabilities

| Domain | Technologies | |--------|-------------| | Deferrable Work | WorkManager 2.10, OneTimeWorkRequest, PeriodicWorkRequest | | Foreground | Foreground Service types (dataSync, location, mediaPlayback, shortService) | | Constraints | NetworkType, BatteryNotLow, StorageNotLow, DeviceIdle | | Chaining | WorkContinuation, parallel chains, unique work policies | | Testing | TestWorkerBuilder, TestListenableWorkerBuilder, WorkManagerTestInitHelper |

Architecture Patterns

WorkManager Decision Tree

Is the task user-initiated and needs to complete?
  ├─ YES → Is it short (< 10 min)?
  │   ├─ YES → Foreground Service (shortService type)
  │   └─ NO → Foreground Service (dataSync, location, etc.)
  │
  └─ NO → Is it deferrable?
      ├─ YES → WorkManager
      │   ├─ One-time? → OneTimeWorkRequest
      │   └─ Periodic? → PeriodicWorkRequest (min 15 min interval)
      │
      └─ NO → Is it while app is visible?
          ├─ YES → CoroutineScope (viewModelScope or lifecycleScope)
          └─ NO → You probably need WorkManager anyway

CoroutineWorker with Retry and Progress

@HiltWorker
class SyncWorker @AssistedInject constructor(
    @Assisted context: Context,
    @Assisted params: WorkerParameters,
    private val syncRepository: SyncRepository,
    private val notificationHelper: NotificationHelper,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // Report progress for UI observation
        setProgress(workDataOf("progress" to 0))

        return try {
            val pendingItems = syncRepository.getPendingChanges()

            pendingItems.forEachIndexed { index, item ->
                syncRepository.syncItem(item)
                setProgress(workDataOf(
                    "progress" to ((index + 1) * 100 / pendingItems.size)
                ))
            }

            Result.success(workDataOf("synced" to pendingItems.size))
        } catch (e: IOException) {
            if (runAttemptCount < 3) {
                Result.retry()  // Exponential backoff by default
            } else {
                Result.failure(workDataOf("error" to e.message))
            }
        }
    }

    override suspend fun getForegroundInfo(): ForegroundInfo {
        return ForegroundInfo(
            NOTIFICATION_ID,
            notificationHelper.createSyncNotification()
        )
    }
}

Scheduling with Constraints and Chaining

// Schedule periodic sync every 1 hour (minimum 15 min)
val syncRequest = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
    .setConstraints(
        Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .setRequiresBatteryNotLow(true)
            .build()
    )
    .setBackoffCriteria(
        BackoffPolicy.EXPONENTIAL,
        WorkRequest.MIN_BACKOFF_MILLIS,
        TimeUnit.MILLISECONDS
    )
    .addTag("sync")
    .build()

WorkManager.getInstance(context).enqueueUniquePeriodicWork(
    "periodic-sync",
    ExistingPeriodicWorkPolicy.KEEP,  // Don't restart if already scheduled
    syncRequest
)

// Chain: download → process → upload (sequential)
WorkManager.getInstance(context)
    .beginWith(downloadWork)
    .then(processWork)
    .then(uploadWork)
    .enqueue()

Anti-Patterns

1. AlarmManager for deferrable work — AlarmManager alarms are not Doze-compatible and drain battery. Use WorkManager which respects Doze, App Standby, and battery saver.
2. Background Service without foreground notification — Android 12+ kills background services. Use Foreground Service with proper type declaration or WorkManager.
3. PeriodicWork under 15 minutes — WorkManager enforces a minimum 15-minute interval. For more frequent work, use Foreground Service or coroutine with lifecycle awareness.
4. Not declaring foreground service type — Android 14+ requires explicit foregroundServiceType in manifest. Omitting it causes SecurityException.
5. Ignoring work observation — starting work but not showing progress to users. Observe WorkInfo via getWorkInfoByIdLiveData() or getWorkInfoByIdFlow() to update UI.

Quality Checklist

[ ] WorkManager used for deferrable background tasks (not AlarmManager)
[ ] Foreground Service declared with correct type in AndroidManifest
[ ] Constraints configured (network, battery, storage)
[ ] Retry policy with backoff for transient failures
[ ] Unique work policy set for periodic/one-time work
[ ] Work progress observable from UI
[ ] Doze mode tested via adb: `adb shell dumpsys deviceidle force-idle`
[ ] Battery optimization tested: `adb shell am set-inactive <package> true`
[ ] Workers tested with TestWorkerBuilder
[ ] Notification channels created for foreground service notifications
[ ] Work chains handle partial failure gracefully
[ ] Background work respects user's battery saver preference