Welcome to kmpworkmanager Discussions!

[vietnguyentuan2019]

👋 Welcome!

We’re using Discussions as a place to connect with other members of our community. We hope that you:

• Ask questions you’re wondering about.
• Share ideas.
• Engage with other community members.
• Welcome others and are open-minded. Remember that this is a community we
  build together 💪.

To get started, comment below with an introduction of yourself and tell us about what you do with this community.

[filipceko]

Hey there,
nice work on the library. It seems useful and covers a lot of cases.

I would like to use it in our KMP app but I am struggling with registering the task execution on iOS platform.
We have a Koin setup and I created a simple object in Kotlin with Koin access. It should get executed on app start where I would like to register the task launcher handler using BGTaskScheduler.

The problem is I can't find the correct library endpoint to delegate to.
In the docs here I see I should inject BackgroundTaskScheduler and call method handleSingleTask(task, identifier), but there is no such method defined on that interface.

Am I missing something?

Thank you! :)

[vietnguyentuan2019]

Hi @filipceko, thank you for reaching out!

I have investigated the issue and confirmed that the documentation was indeed referencing an API that hadn't been fully exposed in the library yet.

Good news: I have found the root cause and already implemented a fix in the upcoming v2.4.0 release. This includes a new native Kotlin API (IosBackgroundTaskHandler) that handles all the background task lifecycle logic automatically, so you won't need to maintain that long Swift boilerplate anymore.

I am currently finalizing the code structure and running an extensive test suite on physical devices to ensure rock-solid stability. I will notify you here as soon as the new version is published. Stay tuned!

[filipceko]

Great news, thank you! 👍

[vietnguyentuan2019]

i @filipceko, apologies for the confusion! v2.4.0 is now released and addresses this mismatch.

The correct API is now IosBackgroundTaskHandler. You can delegate the task handling in your AppDelegate (or Kotlin code) like this:

BGTaskScheduler.shared.register(forTaskWithIdentifier: "your-task-id", using: nil) { task in
IosBackgroundTaskHandler.shared.handleSingleTask(
task: task as! BGTask,
scheduler: koin.getScheduler(),
executor: koin.getSingleTaskExecutor()
)
}

We've also added a Simulator Fallback in this version so tasks will execute immediately during local testing.

Details: v2.4.0 Migration Guide (https://github.com/brewkits/kmpworkmanager/blob/main/docs/MIGRATION_V2.4.0.md)

[filipceko]

Great! I will try to integrate, but would it be possible to upload the. version to maven central?

[vietnguyentuan2019]

Hi @filipceko! Good news — version v2.4.0 is already available on Maven Central.

You can add it to your project with:

implementation("dev.brewkits:kmpworkmanager:2.4.0")

It usually takes a few hours for the search index on central.sonatype.com to update after the initial sync, but the artifact is live and ready to use. Thanks for your patience!

[filipceko]

Hello,
I am sorry to bother you further but I have encountered another problem.

I try to schedule some tasks that are generated at runtime. Something like you have shown in the example:

scheduler.enqueue(
    id = "photo-upload-${photoId}",
    trigger = TaskTrigger.OneTime(),
    workerClassName = "PhotoUploadWorker",
    constraints = Constraints(
        requiresNetwork = true,
        requiresUnmeteredNetwork = true, // WiFi only
        backoffPolicy = BackoffPolicy.EXPONENTIAL,
        backoffDelayMs = 10_000 // 10s → 20s → 40s → 80s
    ),
    inputJson = """{"photoId": "$photoId"}"""
)

The problem is that on iOS I would have to register every possible task with photo ID. I could just provide the ID in the task parameters but then the scheduler will treat the tasks as the same task.

Is there a way to work around this?

[vietnguyentuan2019]

Draft Response for GitHub Discussion #8

Hi @filipceko,

Thank you for reporting this issue! You have encountered a fundamental limitation in how Apple designed BGTaskScheduler on iOS.

Unlike Android's WorkManager, iOS requires all background task identifiers to be statically declared in the Info.plist file under BGTaskSchedulerPermittedIdentifiers before compilation. As a result, dynamically generating IDs at runtime (like photo-upload-${photoId}) will cause the OS to immediately reject the task.

Furthermore, using a workaround where you declare a single static ID (e.g., photo-upload) and pass the dynamic ID as parameters will cause iOS to treat them as the same task. Because of this, if you schedule 3 photos in a row, iOS will overwrite the previous pending tasks, which leads to the data loss you're experiencing.

🛠 The Immediate Workaround (App-Level Dispatcher Pattern)

To solve this right now without waiting for a library update, you need to implement a Dispatcher Pattern using a local queue:

1. Store Tasks Locally: Instead of calling schedule for every photo, insert the photo upload requests into a local database (like Room, SQLDelight, or even SharedPreferences/File storage).
2. Use a Single Static ID: Define one static task ID like dev.mycompany.app.photo_dispatcher and add it to your Info.plist.
3. Batch Execution: Call KMPWorkManager.schedule("dev.mycompany.app.photo_dispatcher"). When your Worker's doWork() function is executed by iOS, have it query your local database and upload all pending photos concurrently or sequentially.

We have just published a detailed guide on this limitation and the workaround here: iOS Dynamic Task Scheduling Guide

🚀 Our Future Plan

We completely agree that this is a frustrating platform disparity. KMP WorkManager should abstract this away!

We are tracking this as a major architectural feature request for an upcoming minor/major release (v2.5.0 or v3.0.0). The goal is to build an Internal Dispatcher Queue directly into the library's iosMain source set. Once implemented, you will be able to call schedule(dynamic_id) on iOS just like you do on Android, and the library will transparently handle the internal queuing and dispatching for you.

Thank you again for the feedback, and please let us know if the workaround helps in the meantime!

[filipceko]

Thank you for clarification.

For the time being we managed to make do without this mechanism and registered all of the tasks separately. However, support of dynamic tasks will be much appreciated later. In case we will require them earlier, I will let you know, but as you mentioned, the dispatcher patter seems like the right way to go.

I just wanted to clarify since such usage was part of the examples.

Thank you once again and best of luck!

[vietnguyentuan2019]

🎉 Fully Resolved in v2.4.1: Seamless Dynamic Task Scheduling on iOS

Hi everyone,

I'm thrilled to announce that we have officially addressed this limitation in the latest v2.4.1 release! We’ve implemented a comprehensive architectural solution that makes iOS background scheduling as dynamic and flexible as Android’s WorkManager.

🚀 The Solution: App-Level "Master Dispatcher"

Instead of forcing you to register every single task ID in your Info.plist, we’ve introduced an internal routing layer.

1. Single Registration: You now only need to register one identifier in your Info.plist: kmp_master_dispatcher_task.
2. Transparent Routing: When you call scheduler.enqueue(id = "my-dynamic-uuid", ...) with an ID that isn't in your plist, the library automatically routes it to an internal high-performance AppendOnlyQueue.
3. Autonomous Execution: When the system wakes up the Master Dispatcher, it automatically drains the queue, respects task-level constraints, and manages the background execution budget to prevent SIGKILL.

⚡ Key Improvements in v2.4.1:

• Dynamic IDs: Use unlimited, runtime-generated task identifiers without configuration changes.
• Memory Efficiency: Metadata scanning now uses a streaming Sequence (O(1) memory), making it safe for apps with tens of thousands of pending tasks.
• Reliability: Added atomic file operations and "Zombie Coroutine" protection to ensure your tasks are either fully executed or safely re-queued if iOS preempts the app.
• Periodic Control: New initialDelayMs and runImmediately flags to give you absolute control over when a periodic task starts.

📦 Get Started:

Update your dependencies to version 2.4.1.

Check out the updated documentation on iOS Dynamic Task Scheduling for full implementation details.

Thank you for the great discussion that pushed this library to a new level of maturity!