Simplifies scheduling and executing periodic background jobs with a simple API, flexible intervals, and platform-specific implementations for Android and iOS. Offers customizable job logic.
A Kotlin Multiplatform library that simplifies scheduling and executing periodic background jobs across different platforms (iOS, and Android). This library provides an easy-to-use API for setting up jobs that run at specified intervals, ensuring that your application can perform tasks in the background efficiently.
NOTE: This library is in pre-release phase. Stable release publishing is expected to be by July 20th 2025.
For android this library uses Android Work Manager to schedule jobs, which has an easy setup and it's all at runtime. However on iOS side of things, the job identifiers need to be registered at compile/build time of the application. For iOS these unique identifiers are setup in the target's Info.plist file.
To achieve a common solution this uses a gradle plugin, that let you define your background job identifiers in your build setup which stays common between the platforms and provides a solution where you don't have to manually setup the identifiers in your iOS setup and copy that on Android for reference in your common/shared code.
Add the following gradle plugin in your build.gradle.kts of shared/common gradle module that is shared between Android & iOS
plugins {
id ("io.github.kprakash2.kmp-workmanager-gradle") version "<version>"
}
Add the following block in your build.gradle.kts of shared/common gradle module that is shared between Android & iOS
kmpworkmanager {
jobIdentifiers = setOf<String>(<JOB_ID1>, <JOB_ID2>, ...)
iosAppInfoPlistPath = <Path to your iOSApp's Info.plist file>
packageName = <root package name for your module's source set>
sourceSetDirectory = <path to your modules source set>
className = <background job type enum class name> // default: `BackgroundJobIdentifiers`
}
jobIdentifiers: Set of identifiers for your background jobs. Identifiers should be all upper case and without any whitespaces.iosAppInfoPlistPath: Path to your iOS App's Info.plist file. Usually it will be similar to ../iosApp/iosApp/Info.plistThe above extension will configure all compile type tasks in your module to run prepareKmpWorkManagerConfig which will create a config file in your source set which you can use to register your jobs at runtime.
To include the library in your Kotlin Multiplatform project, add the following dependencies in your shared module's build.gradle.kts file:
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("io.github.kprakash2:kmp-workmanager:<version>")
}
}
}
}
Once you have compiled your project with above setup, in your module's sourceset there would be enum class (BackgroundJobIdentifiers or className if you provided the parameter in kmpWorkManager configuration) available with all your job identifiers.
This provider should return a BackgroundJob type for all your background job identifiers.
class MyBackgroundJobProvider(): BackgroundJobProvider<BackgroundJobIdentifiers> {
override suspend fun <T: BackgroundJobType> getBackgroundJob(type: T): BackgroundJob {
return when (type as BackgroundJobIdentifiers) {
...
...
}
}
}
You can declare the following function or also tie it to your dependency injection framework if you're using any and then call this from each platform specific code.
Note: context can be null for iOS, it's only required for Android platform.
// In commonMain
fun initializeBackgroundWorkRepository(context: Any?) {
BackgroundWorkRepository.initialize(
context, // This can be null for iOS
MyBackgroundJobProvider()
)
}
// In androidMain
initializeBackgroundWorkRepository(context)
// In iosMain
initializeBackgroundWorkRepository(null)
You can configure each of your background job type with multiple parameters using BackgroundJobConfiguration
val backgroundWorkRepository = BackgroundWorkRepository.getInstance()
val jobsConfiguration = BackgroundJobIdentifiers.entries.map {
it to when (it) {
BackgroundJobIdentifiers.<id> -> BackgroundJobConfiguration(...)
....
}
}
backgroundWorkRepository.registerJobs(jobsConfiguration)
BackgroundWorkRepository.getInstance(): Provide an instance of BackgroundWorkRepository. Make sure to call before this. val backgroundWorkRepository = BackgroundWorkRepository.getInstance()
backgroundWorkRepository.schedule(...)
val backgroundWorkRepository = BackgroundWorkRepository.getInstance()
backgroundWorkRepository.cancelJob(...)
Example:
BackgroundJobConfiguration(
intervalInMillis = 900000,
periodic = true,
supportedPlatform = SupportedPlatform.ALL
)
intervalInMillis: Represents interval between each periodic task run in milliseconds. Both Android and iOS only support 15 minutes of minimum interval.shared modulekmp-workmanager pluginCopyright 2025 Kartik Prakash
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
packageName: Root Package name of your module's sourceset.sourceSetDirectory: File property pointing to your module's common source set. Usually it will be similar to project.file("src/commonMain/kotlin")classNme: This is optional, if you'd like to use a custom name of the background job type enum class name.BackgroundWorkRepository.initialize()BackgroundJobConfiguration: Represents the configuration for your background jobbackgroundWorkRepository.registerJobs(..): Registers all of your background job. Make sure to call this before you call backgroundWorkRepository.schedule(...). This is specially required for iOS platform as we need to register all BGApp tasks before they can be scheduled. See Apple documentation for more details.periodic: If task is recurring, this should be set to true. If the task needs to be run just once, this should be set to false.supportedPlatform: Represents the platform on which the task should run. It can be ANRDOID_ONLY, IOS_ONLY, ALL. If you want your task to run on both Android and IOS, use ALL.Surfaced from shared tags and platforms — no rankings paid for.