Background work, notifications and WorkManager

WorkManager with constraints and backoff, unique and chained work, foreground services, and notification channels and permissions.

WorkManager and constraints

class SyncWorker(
    appContext: Context,
    params: WorkerParameters,
    private val repo: BookRepository,
) : CoroutineWorker(appContext, params) {

    override suspend fun doWork(): Result {
        val since = inputData.getLong(KEY_SINCE, 0L)
        return try {
            // idempotent: re-running must be safe
            repo.syncSince(since)
            Result.success()
        } catch (e: IOException) {
            if (runAttemptCount < 5) Result.retry() else Result.failure()
        }
    }

    companion object { const val KEY_SINCE = "since" }
}

@HiltWorker
class SyncWorker @AssistedInject constructor(
    @Assisted appContext: Context,
    @Assisted params: WorkerParameters,
    private val repo: BookRepository,
) : CoroutineWorker(appContext, params) {
    override suspend fun doWork(): Result = runCatching { repo.sync() }
        .fold({ Result.success() }, { if (runAttemptCount < 5) Result.retry() else Result.failure() })
}

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

WorkManager.getInstance(context)
    .enqueueUniquePeriodicWork(
        "sync",
        ExistingPeriodicWorkPolicy.KEEP,
        PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
            .setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build())
            .build(),
    )

• WorkManager persists the request, so work survives process death and a device reboot. It is the right tool for anything that must eventually happen.
• Periodic work has a 15-minute minimum. If you need something faster, that is a foreground service or a push message, not a shorter interval.
• The unique work name prevents duplicates but does nothing about concurrency. ExistingPeriodicWorkPolicy.UPDATE replaces the definition, while KEEP leaves an existing one alone.
• Every worker must be idempotent: the system can retry after a crash, and the retry happens without warning.

Chaining and observing

val download = OneTimeWorkRequestBuilder<DownloadWorker>().build()
val process = OneTimeWorkRequestBuilder<ProcessWorker>().build()
val upload = OneTimeWorkRequestBuilder<UploadWorker>().build()

WorkManager.getInstance(context)
    .beginWith(download)
    .then(process)
    .then(upload)
    .enqueue()

// observe progress from the UI
WorkManager.getInstance(context)
    .getWorkInfosForUniqueWorkFlow("sync")
    .map { infos -> infos.firstOrNull()?.state ?: WorkInfo.State.ENQUEUED }
    .distinctUntilChanged()

// pass data between workers
val output = workDataOf(KEY_FILE to path)
// setOutputData(output) in the worker; the next worker reads inputData

// cancellation
WorkManager.getInstance(context).cancelUniqueWork("sync")

Foreground services and notifications

class UploadService : LifecycleService() {

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val notification = NotificationCompat.Builder(this, CHANNEL_ID)
            .setContentTitle("Uploading")
            .setSmallIcon(R.drawable.ic_upload)
            .setOngoing(true)
            .setProgress(0, 0, true)
            .build()

        ServiceCompat.startForeground(this, NOTIFICATION_ID, notification, FOREGROUND_TYPE)

        lifecycleScope.launch {
            try {
                uploader.run()
            } finally {
                stopSelf()
            }
        }
        return START_NOT_STICKY
    }
}

// create the channel once, at application start
val channel = NotificationChannel(
    CHANNEL_ID, "Uploads", NotificationManager.IMPORTANCE_LOW,
).apply { description = "Background upload progress" }
context.getSystemService(NotificationManager::class.java).createNotificationChannel(channel)

// Android 13+ requires the runtime permission before posting anything
// <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
val launcher = rememberLauncherForActivityResult(RequestPermission()) { granted ->
    if (!granted) showRationale()
}
launcher.launch(Manifest.permission.POST_NOTIFICATIONS)

• Android 14 requires a declared foreground service type in the manifest and a matching permission. Starting one without it throws, so declare the type you actually need.
• A foreground service must post a notification and must start it within a few seconds of startForegroundService or the system kills the process.
• Notifications require the runtime permission on Android 13+. Ask in context, when the user starts the action that needs it, not on first launch.
• Channels are created once and cannot have their importance changed by the app afterwards - the user owns that. Get the importance right in the first release.
• Use IMPORTANCE_LOW for progress and IMPORTANCE_HIGH only for something genuinely time-critical, or users will turn the channel off.

FAQ

Related

Permissions, storage and publishing Testing Android apps

Last refreshed 2026-09-18.