Android WorkManager guide

dependencies {
    implementation "androidx.work:work-runtime-ktx:2.9.0"
}

class ImageUploadWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val imageUri = inputData.getString("IMAGE_URI") ?: return Result.failure()
        
        return try {
            // Simulate network upload with retry logic
            val success = uploadImageToServer(imageUri)
            
            if (success) {
                Result.success()
            } else {
                // Retry with exponential backoff
                Result.retry()
            }
        } catch (e: Exception) {
            // Permanent failure due to unexpected error
            Result.failure()
        }
    }

    private suspend fun uploadImageToServer(uri: String): Boolean {
        // Implementation of upload logic
        return true
    }
}

val constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresBatteryNotLow(tr

ue) .setRequiresCharging(false) .build()

### Step 3: Enqueue Work Requests

Create and enqueue work requests with appropriate policies. Use `setExpedited()` for urgent work that should run immediately if resources allow.

```kotlin
val uploadRequest = OneTimeWorkRequestBuilder<ImageUploadWorker>()
    .setConstraints(constraints)
    .setBackoffCriteria(
        BackoffPolicy.EXPONENTIAL,
        OneTimeWorkRequest.MIN_BACKOFF_MILLIS,
        TimeUnit.MILLISECONDS
    )
    .setInputData(workDataOf("IMAGE_URI" to "content://image/123"))
    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED)
    .build()

WorkManager.getInstance(context).enqueue(uploadRequest)

Step 4: Chaining and Complex Workflows

WorkManager supports complex workflows via WorkContinuation. This allows sequential and parallel execution with input/output merging.

val compressWork = OneTimeWorkRequestBuilder<ImageCompressWorker>().build()
val uploadWork = OneTimeWorkRequestBuilder<ImageUploadWorker>().build()
val notifyWork = OneTimeWorkRequestBuilder<NotifyUserWorker>().build()

WorkManager.getInstance(context)
    .beginWith(compressWork)
    .then(uploadWork)
    .then(notifyWork)
    .enqueue()

Step 5: Observing Results

Observe LiveData to update the UI based on work status.

WorkManager.getInstance(context)
    .getWorkInfoByIdLiveData(uploadRequest.id)
    .observe(viewLifecycleOwner) { workInfo ->
        if (workInfo?.state == WorkInfo.State.SUCCEEDED) {
            // Update UI
        }
    }

Architecture Rationale

• CoroutineWorker: Preferred over Worker for tasks involving I/O or network calls. It provides structured concurrency and automatic cancellation support.
• BackoffPolicy: Essential for transient failures. EXPONENTIAL backoff prevents server overload and respects network conditions.
• setExpedited: Use for tasks that must run quickly while the app is in the foreground. It falls back to standard scheduling if the expedited quota is exceeded.
• InputMerger: Default OverwritingInputMerger is sufficient for most cases. Custom mergers are needed for aggregating outputs from parallel workers.

Pitfall Guide

1. Missing BackoffPolicy Configuration

Mistake: Failing to set BackoffPolicy when returning Result.retry(). Impact: The worker will retry immediately, potentially causing a tight loop that drains battery and floods logs. Best Practice: Always configure setBackoffCriteria with EXPONENTIAL or LINEAR policy.

2. Over-Constraining Tasks

Mistake: Setting constraints that are rarely met, such as requiring charging and unmetered network simultaneously. Impact: Work never executes. Users report data not syncing. Best Practice: Review constraints critically. Only add constraints that are strictly necessary for task success. Use setRequiredNetworkType(NetworkType.CONNECTED) as a baseline.

3. Blocking Main Thread in doWork

Mistake: Performing long-running operations on the main thread within a Worker (non-coroutine). Impact: ANR (Application Not Responding) or process kill. Best Practice: Use CoroutineWorker for async operations. If using Worker, ensure all work is offloaded to background threads.

4. Ignoring setExpedited for Urgent Work

Mistake: Enqueuing standard work for tasks that must complete before the user leaves the app. Impact: Work may be delayed until constraints are met or the app enters the background. Best Practice: Use setExpedited() for urgent tasks. Be aware of the quota limits and define OutOfQuotaPolicy.

5. Memory Leaks via Context References

Mistake: Holding a strong reference to Context or Activity in the Worker class fields. Impact: Memory leaks if the worker outlives the activity. Best Practice: Use applicationContext or pass only necessary data via InputData. Avoid storing context references.

6. Not Handling Result.failure() Data

Mistake: Returning Result.failure() without output data when the UI needs error details. Impact: UI cannot display meaningful error messages. Best Practice: Use Result.failure(outputData) to pass error codes or messages back to observers.

7. Duplicate Work Enqueueing

Mistake: Calling enqueue() repeatedly without unique work policies. Impact: Multiple identical tasks run, wasting resources and causing duplicate side effects. Best Practice: Use WorkManager.enqueueUniqueWork() with ExistingWorkPolicy.REPLACE or KEEP to manage duplicates.

Production Bundle

Action Checklist

• Add work-runtime-ktx dependency and verify version compatibility.
• Implement CoroutineWorker for all asynchronous tasks.
• Define Constraints based on actual task requirements; avoid over-constraining.
• Configure BackoffPolicy for any task that may return Result.retry().
• Use setExpedited() for urgent tasks with appropriate OutOfQuotaPolicy.
• Implement WorkQuery and pruneWork() for storage management in long-running apps.
• Observe WorkInfo via LiveData or Flow to update UI state.
• Test work execution under Doze mode and network disconnection scenarios.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Immediate sync before user action	setExpedited()	Runs immediately if quota allows; falls back gracefully	Higher battery if frequent
Periodic log upload	PeriodicWorkRequest	System batches work; respects min interval (15m)	Low
Long running task (>10 mins)	ForegroundInfo	Prevents process kill; requires notification	Medium; user notification required
Simple network call	CoroutineWorker	Async, cancellable, integrates with coroutines	Low
Complex dependency graph	WorkContinuation	Handles sequencing and input merging automatically	Low
One-time urgent task	OneTimeWorkRequest + setExpedited	Balances urgency with system constraints	Medium

Configuration Template

Custom WorkManager initialization for advanced configuration.

class MyWorkManagerInitializer : Initializer<WorkManager> {
    override fun create(context: Context): WorkManager {
        val config = Configuration.Builder()
            .setMinimumLoggingLevel(Log.DEBUG)
            .setWorkerFactory(MyWorkerFactory())
            .build()
        
        WorkManager.initialize(context, config)
        return WorkManager.getInstance(context)
    }

    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
}

AndroidManifest.xml:

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data
        android:name="com.example.MyWorkManagerInitializer"
        android:value="androidx.startup" />
</provider>

Quick Start Guide

1. Add Dependency: Include implementation "androidx.work:work-runtime-ktx:2.9.0" in build.gradle.
2. Create Worker: Extend CoroutineWorker and implement doWork() with your task logic.
3. Enqueue Request: Build a OneTimeWorkRequest with constraints and call WorkManager.getInstance(context).enqueue(request).
4. Observe Status: Use getWorkInfoByIdLiveData(request.id) to monitor progress and update the UI.
5. Test: Verify execution using Android Studio's Device File Explorer or logs, ensuring work persists across process death.