This skill maps iOS BackgroundTasks (using BGTaskScheduler) to Android
WorkManager, focusing on modern Jetpack practices and respecting Android's
strict background execution limits.
Official Reference Links:
- Schedule tasks with WorkManager | Android Developers
- Define work requests | Android Developers
- Test your WorkManager implementation | Android Developers
Prerequisites
Before using this skill, you Must ensure the following prerequisites are met:
- Source Context: Access to the existing iOS implementation using
BGTaskSchedulerorAppDelegatebackground fetch is Mandatory. - Software Requirements: Android SDK API Level 34+ (
compileSdk = 34, required for Android 14 mandatory foreground service type declarations), Android Gradle Plugin (AGP) 8.0+, Kotlin 1.8+, and Jetpack WorkManager (androidx.work:work-runtime-ktx:2.9.0) are Mandatory. - Dependency: You Must have the
androidx.work:work-runtime-ktxdependency added to yourbuild.gradle.kts.
Limitations
This skill has the following limitations:
- Exact Timing:
WorkManagerdoes not guarantee exact execution timing. It is subject to OS-level optimizations, including Doze mode and App Standby Buckets. You Must Not use it for tasks requiring immediate or precise timing (use Foreground Services or AlarmManager instead). - Foreground Services: This skill does not cover continuous foreground processing (e.g., active navigation or music playback).
Glossary
| iOS Term | Android Equivalent | Definition |
|---|---|---|
BGTaskScheduler |
WorkManager |
The system service that manages background work. |
BGAppRefreshTask |
PeriodicWorkRequest |
A request for work that repeats periodically. |
BGProcessingTask |
OneTimeWorkRequest |
A request for work that runs exactly once. |
Info.plist identifiers |
Worker classes |
In Android, tasks are defined by creating specific Worker classes rather than registering IDs in a plist. |
Setup & Dependencies
You Must add the following dependency to your build.gradle.kts file:
dependencies {
val workVersion = "2.8.1"
implementation("androidx.work:work-runtime-ktx:$workVersion")
// For testing WorkManager
androidTestImplementation("androidx.work:work-testing:$workVersion")
}
Instructions: Mapping Concepts
1. Configuration & Submission
Registering Tasks
- iOS: Register task identifiers in
Info.plistand callBGTaskScheduler.shared.register. - Android: Inherently handled by declaring standard
Workerclasses and enqueuing them. No manifest registration for specific tasks is required.
Submitting Tasks
- iOS:
BGTaskScheduler.shared.submit(request) - Android:
WorkManager.getInstance(context).enqueue(workRequest)
Setting Criteria/Constraints
- iOS:
request.requiresNetworkConnectivity = true - Android:
Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build()
2. Code Examples
iOS (Reference)
let request = BGAppRefreshTaskRequest(identifier: "com.example.refresh")
request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
try? BGTaskScheduler.shared.submit(request)
Android (Target)
You Must use CoroutineWorker for Kotlin-first background work.
import android.content.Context
import androidx.work.CoroutineWorker
import androidx.work.WorkerParameters
import androidx.work.OneTimeWorkRequestBuilder
import androidx.work.Constraints
import androidx.work.NetworkType
import androidx.work.WorkManager
import java.util.concurrent.TimeUnit
// 1. Define the Worker
class SyncWorker(appContext: Context, workerParams: WorkerParameters) :
CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
// Perform the background sync here
val success = performSync()
return if (success) {
Result.success()
} else {
Result.retry() // Triggers exponential backoff
}
}
private suspend fun performSync(): Boolean {
// Implementation
return true
}
}
// 2. Enqueue the Work
fun scheduleSync(context: Context) {
// You Must evaluate the task's impact on battery.
// If the task is non-critical and can be deferred until the device is charging,
// you Must apply the constraint: .setRequiresCharging(true).
val constraints = Constraints.Builder()
.setRequiredNetworkType(NetworkType.CONNECTED)
.setRequiresCharging(true)
.build()
val syncWorkRequest = OneTimeWorkRequestBuilder<SyncWorker>()
.setConstraints(constraints)
.setInitialDelay(15, TimeUnit.MINUTES)
.build()
WorkManager.getInstance(context).enqueue(syncWorkRequest)
}
3. Production Insight: Centralizing Background Logic
In large-scale production applications dealing with offline sync:
- iOS Real-World Implementation: Employs
BGTaskSchedulernatively, registered withinAppDelegate, invoking single manager classes (like aBackgroundSyncManager.swift) to orchestrate downloads. - Android Real-World Equivalent: Android completely offloads this to
Jetpack
WorkManager. Instead of a single manager handling multiple sync flows, the architecture uses discreteWorkerclasses tailored for specialized tasks (e.g.,RefreshDataWorker,DownloadContentWorker,SyncWorker).
Key Takeaway: Do not try to replicate a monolithic BackgroundSyncManager
inside an Android Service. Break down the iOS background operations into
discrete, chainable Worker classes for reliable execution under Android's
strict background execution limits.
4. Chaining Work
WorkManager allows for a sequence of dependent tasks (e.g., A must finish before
B starts) using .beginWith(...).then(...). This declarative chaining is not a
built-in feature of the base iOS BGTaskScheduler API.
val cleanupRequest = OneTimeWorkRequestBuilder<CleanupWorker>().build()
val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>().build()
WorkManager.getInstance(context)
.beginWith(cleanupRequest)
.then(syncRequest)
.enqueue()
5. Expedited & Foreground Work on Android 14+ (API 34+)
When long-running work requires foreground execution (e.g. active sync, media
processing), you MUST configure ForegroundInfo and declare the mandatory
android:foregroundServiceType attribute in AndroidManifest.xml:
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<!-- or FOREGROUND_SERVICE_HEALTH, FOREGROUND_SERVICE_LOCATION based on capability -->
<application ...>
<service
android:name="androidx.work.impl.foreground.SystemForegroundService"
android:foregroundServiceType="dataSync"
android:exported="false" />
</application>
In your CoroutineWorker, set foreground info with the matching notification
and type:
override suspend fun doWork(): Result {
setForeground(getForegroundInfo())
return performSync()
}
private fun getForegroundInfo(): ForegroundInfo {
val notification = createNotification()
return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
ForegroundInfo(NOTIFICATION_ID, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC)
} else {
ForegroundInfo(NOTIFICATION_ID, notification)
}
}
5. Logic: Choosing the Right WorkRequest
To determine the correct Android WorkRequest, you Must follow this logic:
- IF the iOS task is a one-time, deferrable operation (e.g.,
BGProcessingTaskfor database cleanup), THEN you Must use aOneTimeWorkRequest. - ELSE IF the iOS task is for fetching fresh content on a recurring
schedule (e.g.,
BGAppRefreshTask), THEN you Must use aPeriodicWorkRequest.
6. Unique Work (Avoiding Duplicates)
To prevent multiple instances of the same task from running concurrently or queuing up unnecessarily, you Must use Unique Work.
import androidx.work.ExistingWorkPolicy
import androidx.work.ExistingPeriodicWorkPolicy
// For OneTime Work
WorkManager.getInstance(context).enqueueUniqueWork(
"uniqueSyncTask",
ExistingWorkPolicy.KEEP, // Keep existing, ignore new
syncWorkRequest
)
// For Periodic Work
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"uniquePeriodicSyncTask",
ExistingPeriodicWorkPolicy.KEEP,
periodicSyncWorkRequest
)
7. Observing Work State
You can observe the state of work to update the UI or trigger other actions.
WorkManager.getInstance(context)
.getWorkInfoByIdLiveData(syncWorkRequest.id)
.observe(lifecycleOwner) { workInfo ->
if (workInfo != null && workInfo.state == WorkInfo.State.SUCCEEDED) {
// Show success message
}
}
8. Periodic Work with Flex Interval
If you need to run work periodically but want to restrict it to a specific window within the period (e.g., last 15 minutes of every hour), use flex intervals.
val periodicWork = PeriodicWorkRequestBuilder<SyncWorker>(
1, TimeUnit.HOURS, // Repeat interval
15, TimeUnit.MINUTES // Flex interval
).build()
9. Expedited Work
For tasks that need to run immediately but are still subject to background constraints, use Expedited Work. This is useful for tasks like sending a message or uploading a file that the user just initiated.
import androidx.work.OutOfQuotaPolicy
val request = OneTimeWorkRequestBuilder<SyncWorker>()
.setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
.build()
WorkManager.getInstance(context).enqueue(request)
10. Testing Workers
You Must use work-testing to verify your workers behave correctly without
waiting for system triggers.
@Test
fun testSyncWorker() {
val context = ApplicationProvider.getApplicationContext<Context>()
val worker = TestListenableWorkerBuilder<SyncWorker>(context).build()
runBlocking {
val result = worker.doWork()
assertThat(result, `is`(ListenableWorker.Result.success()))
}
}
@Test
fun testSyncWorkerWithInput() {
val context = ApplicationProvider.getApplicationContext<Context>()
val inputData = Data.Builder()
.putString("KEY_URL", "https://example.com/api")
.build()
val worker = TestListenableWorkerBuilder<SyncWorker>(context)
.setInputData(inputData)
.build()
runBlocking {
val result = worker.doWork()
assertThat(result, `is`(ListenableWorker.Result.success()))
}
}
11. Decision Table: WorkManager vs AlarmManager
You Must use this table to evaluate whether to use WorkManager or
AlarmManager for background tasks:
| Requirement | Recommended API | Rationale |
|---|---|---|
| Exact timing required (e.g., calendar alarm). | AlarmManager | Guarantees execution at the specified time, bypassing Doze mode if necessary. |
| Deferrable work with constraints (e.g., sync when charging). | WorkManager | Optimizes battery by batching work and respecting OS constraints. |
| High-priority task needing immediate execution. | WorkManager (Expedited) | Runs immediately while still respecting system quotas. |
12. Data Handling: Input & Output
You Must use Data objects to pass parameters to and return results from
Workers.
// Passing Input Data
val inputData = Data.Builder()
.putString("KEY_ACTION", "SYNC")
.build()
val request = OneTimeWorkRequestBuilder<SyncWorker>()
.setInputData(inputData)
.build()
// Returning Output Data in Worker
class SyncWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
override suspend fun doWork(): Result {
val action = inputData.getString("KEY_ACTION")
// ...
val outputData = Data.Builder()
.putInt("KEY_ITEMS_SYNCED", 42)
.build()
return Result.success(outputData)
}
}
13. Backoff & Retry Policies
You Must evaluate the retry strategy for failing tasks. Use
.setBackoffCriteria() to control retry behavior.
val request = OneTimeWorkRequestBuilder<SyncWorker>()
.setBackoffCriteria(
BackoffPolicy.EXPONENTIAL,
OneTimeWorkRequest.MIN_BACKOFF_MILLIS,
TimeUnit.MILLISECONDS
)
.build()
14. Handling Long-Running Tasks (Foreground Workers)
If a task exceeds the 10-minute execution limit (e.g., downloading a large
file), you Must promote the Worker to a Foreground Service using
setForeground().
class DownloadWorker(appContext: Context, workerParams: WorkerParameters) :
CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
// Promote to foreground service
setForeground(createForegroundInfo())
// Perform long-running download
return Result.success()
}
private fun createForegroundInfo(): ForegroundInfo {
val notification = NotificationCompat.Builder(applicationContext, CHANNEL_ID)
.setContentTitle("Downloading...")
.setSmallIcon(R.drawable.ic_download)
.build()
return ForegroundInfo(NOTIFICATION_ID, notification)
}
}
Antipatterns
DO
- DO use
CoroutineWorkerfor modern Kotlin apps. - DO use
Result.retry()to leverage WorkManager's automatic exponential backoff. - DO chain Worker classes together using
WorkManager.beginWith(...).then(...).enqueue()to manage dependencies. - DO specify constraints (like requiring network) to prevent waste of battery.
- DO use Unique Work to avoid duplicate task execution.
- DO use Expedited Work for high-priority tasks that need to run immediately.
- DO evaluate task impact on battery and use constraints appropriately.
DON'T
- DON'T use
WorkManagerfor tasks that must run at an exact time. UseAlarmManager. - DON'T put large amounts of code directly in the
Activityto trigger background work; delegate to a repository or UseCase. - DON'T assume background work will run immediately unless marked as expedited.
- DON'T pass large amounts of data in the
Dataobject (limit is 10KB). Use a database instead.
NEVER
- NEVER attempt to replicate a monolithic
BackgroundSyncManagerfrom iOS inside a single AndroidServiceorWorker. - NEVER block the thread in
doWork()of aCoroutineWorker. Use suspending functions. - NEVER use
WorkManagerfor tasks that require foreground execution guarantees (like active location tracking). Use a Foreground Service.