Android Background Work

Android Background Work

Overview

Background execution on Android is a negotiation with the OS, not a right. Doze, App Standby buckets, foreground-service type enforcement, and exact-alarm policy all exist to kill battery-hungry work — code that ignores them runs fine on the developer's charging Pixel and silently never runs in the field. This skill picks the correct primitive for each job and makes background work observable and testable.

When to Use

• Syncing data, uploading files, or refreshing content off-screen
• Scheduling periodic or deferred jobs
• Long-running user-initiated tasks (export, media processing)
• Anything currently "solved" with GlobalScope.launch or a raw Service

Skip when: The work only matters while the screen is visible — use viewModelScope/lifecycleScope and let it cancel with the UI.

Core Process

Step 1: Pick the Right Primitive

1. Decision table — default to WorkManager:

Choosing a foreground service for deferrable work, or exact alarms for "roughly hourly", fails Play review and drains battery.

Step 2: WorkManager Done Right

2. Constraints and backoff instead of retry loops:

val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
    .setConstraints(
        Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .setRequiresBatteryNotLow(true)
            .build()
    )
    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
    .build()

// Unique work: a second "sync now" tap must not enqueue a second sync
WorkManager.getInstance(context).enqueueUniqueWork(
    "sync", ExistingWorkPolicy.KEEP, syncRequest
)

3. Worker rules:
   • CoroutineWorker + Result.retry() on transient failures; Result.failure() only for permanent ones
   • Expedited work (setExpedited) for short user-initiated jobs that should dodge Doze — with getForegroundInfo() implemented for the pre-API-31 fallback
   • Workers are re-run after process death: make them idempotent (upsert, not insert)
   • Inject dependencies via Hilt's @HiltWorker + HiltWorkerFactory, not service locators

Step 3: Foreground Services Under Type Enforcement

4. Since API 34 every foreground service declares a type — in the manifest and at start, with the type's prerequisite permission:

<service
    android:name=".playback.PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="false" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

ServiceCompat.startForeground(
    this, NOTIFICATION_ID, notification,
    ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK,
)

Starting with a mismatched or undeclared type throws; dataSync type is being phased out — use WorkManager for transfers. The notification requires POST_NOTIFICATIONS runtime permission on API 33+.

Step 4: Respect Doze and Standby

5. Design for the powered-off case:
   • Doze defers network, jobs, and standard alarms into maintenance windows — WorkManager already cooperates; hand-rolled Handler.postDelayed loops do not
   • App Standby buckets throttle how often deferred work runs — heavy users get more budget than dormant installs; never promise sync freshness the bucket can't deliver
   • setAndAllowWhileIdle is rate-limited (~once/9 min per app) — it is for user-facing alarms, not sync
   • Never ask for REQUEST_IGNORE_BATTERY_OPTIMIZATIONS as a convenience — it's a Play-policy-restricted permission for genuinely exempt app categories

Step 5: Test It Deterministically

6. WorkManager has a real test API — use it instead of sleeping:

@Before
fun setup() {
    val config = Configuration.Builder()
        .setExecutor(SynchronousExecutor())
        .build()
    WorkManagerTestInitHelper.initializeTestWorkManager(context, config)
}

@Test
fun syncWorker_runs_whenConstraintsMet() {
    val request = OneTimeWorkRequestBuilder<SyncWorker>()
        .setConstraints(networkConstraints)
        .build()
    WorkManager.getInstance(context).enqueue(request).result.get()

    // Simulate the OS satisfying constraints
    WorkManagerTestInitHelper.getTestDriver(context)!!
        .setAllConstraintsMet(request.id)

    val info = WorkManager.getInstance(context).getWorkInfoById(request.id).get()
    assertEquals(WorkInfo.State.SUCCEEDED, info.state)
}

7. On-device verification (see android-device-testing):

adb shell dumpsys jobscheduler | grep <package>     # scheduled jobs
adb shell am send-trim-memory <package> RUNNING_CRITICAL
adb shell cmd deviceidle force-idle                  # simulate Doze

Common Rationalizations

Red Flags

• Raw Service or GlobalScope.launch doing deferrable work
• Foreground service without a manifest foregroundServiceType
• dataSync foreground service where WorkManager belongs
• Periodic work under 15 minutes "scheduled" with self-rearming alarms
• Non-idempotent workers (duplicate rows after a retry)
• enqueue instead of enqueueUniqueWork for user-triggerable jobs
• No test using WorkManagerTestInitHelper for critical background flows

Verification

• Each background job maps to the decision table's primitive (state which and why)
• WorkRequests have constraints and backoff; user-triggerable work is unique work
• Workers are idempotent — a forced re-run produces no duplicates
• Foreground services declare types + prerequisite permissions; start succeeds on API 34+
• POST_NOTIFICATIONS flow handled for service notifications (API 33+)
• Tests pass with WorkManagerTestInitHelper (./gradlew test output)
• Behavior verified under cmd deviceidle force-idle for sync-critical flows