Background Processing
Register, schedule, and execute background tasks on iOS using BackgroundTasks (BGTaskScheduler), background URLSession, and background push notifications. Targets Swift 6.4 / iOS 26+.
Contents
Capabilities and Configuration
Every task identifier must be declared in Info.plist under BGTaskSchedulerPermittedIdentifiers, or submit(_:) throws BGTaskScheduler.Error.Code.notPermitted.
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.example.app.refresh</string>
<string>com.example.app.db-cleanup</string>
<string>com.example.app.export.*</string>
</array>
<key>UIBackgroundModes</key>
<array>
<string>fetch</string> <!-- Required for BGAppRefreshTask -->
<string>processing</string> <!-- Required for BGProcessingTask -->
<string>remote-notification</string> <!-- Required for silent push -->
</array>
In Xcode: Target > Signing & Capabilities > Background Modes > enable Background fetch, Background processing, or Remote notifications.
Task Selection Matrix
| Task Type |
Max Duration |
Trigger |
Requires Power/Network |
Use Case |
BGAppRefreshTask |
~30 seconds |
System opportunistic |
Configurable hint |
Light feed/state updates |
BGProcessingTask |
Several minutes |
Device idle |
External power / network optional |
Database cleanup, maintenance, ML indexing |
BGContinuedProcessingTask |
User bounded |
Foreground user action |
Live Activity progress |
Exporting large media, offline bundle generation |
URLSession.background |
Managed out-of-process |
Network completion |
Cellular/WiFi policy |
Large file downloads and uploads |
| Silent Remote Push |
~30 seconds |
APNs trigger (content-available: 1) |
Network required |
Server-driven data invalidation hint |
Core Lifecycle Rules
- Register before launch finishes: Register all handlers in
application(_:didFinishLaunchingWithOptions:) (UIKit) or App.init() (SwiftUI). Submitting an unregistered identifier throws runtime exceptions.
- Re-schedule inside handler: Immediately schedule the next iteration at the beginning of the execution handler so scheduling survives app crashes or task timeouts.
- Always set
expirationHandler: The system can revoke background execution time at any moment. The expiration handler must cancel active tasks and call setTaskCompleted(success: false).
- Call
setTaskCompleted(success:) exactly once: Failing to call completion causes the system to penalize future execution allocations.
- Treat
earliestBeginDate as a lower bound: iOS determines actual launch time based on battery status, power state, and user interaction patterns.
Route by Task
- For full registration code, canonical handlers, and checkpointing, read Canonical Registration and Handlers.
- For simulating task launches with LLDB (
_simulateLaunchForTaskWithIdentifier:), read Debugging Background Tasks.
- For background downloads, uploads, and handling app relaunch in
handleEventsForBackgroundURLSession, read Background URLSession Extended Patterns.
- For background push throttling and payload constraints, read Background Push Extended Patterns.
- For continued processing tasks conforming to
ProgressReporting, read BGContinuedProcessingTask Patterns.
iOS 27 Updates
- Background Neural Engine access is restricted, like GPU limits. Background inference needs the entitlement
com.apple.developer.background-tasks.continued-processing.inference.
UIScene.extendStateRestoration and UIScene.completeStateRestoration extend state restoration across background-to-foreground transitions.
- Apps built with the iOS 27 SDK must use the scene-based life cycle or they fail to launch.
- On Demand Resources and
NSBundleResourceRequest are deprecated; use Background Assets. Background Assets adds localized asset packs, delivered by the user's preferred languages.
Sources: https://sosumi.ai/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes
Common Mistakes
- Submitting a task identifier that is not declared in
BGTaskSchedulerPermittedIdentifiers (throws .notPermitted).
- Forgetting to call
task.setTaskCompleted(success:) on all execution and failure paths.
- Omitting
task.expirationHandler, leading to watchdog termination when background time expires.
- Scheduling app refresh at aggressive minute-scale intervals instead of respecting system heuristics.
- Using async/await convenience APIs or completion closures on background
URLSession (requires delegate).
Review Checklist
References
1---2name: background-processing3description: "Schedules and executes iOS background work with BGTaskScheduler and background URLSession. Use for app refresh, processing, continued-processing tasks, expiration and completion handling, background downloads, background pushes, registration, Info.plist configuration, or launch simulation."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/background-processing6---78# Background Processing910Register, schedule, and execute background tasks on iOS using BackgroundTasks (`BGTaskScheduler`), background `URLSession`, and background push notifications. Targets Swift 6.4 / iOS 26+.1112## Contents1314- [Capabilities and Configuration](#capabilities-and-configuration)15- [Task Selection Matrix](#task-selection-matrix)16- [Core Lifecycle Rules](#core-lifecycle-rules)17- [Route by Task](#route-by-task)18- [iOS 27 Updates](#ios-27-updates)19- [Common Mistakes](#common-mistakes)20- [Review Checklist](#review-checklist)21- [References](#references)2223## Capabilities and Configuration2425Every task identifier must be declared in `Info.plist` under `BGTaskSchedulerPermittedIdentifiers`, or `submit(_:)` throws `BGTaskScheduler.Error.Code.notPermitted`.2627```xml28<key>BGTaskSchedulerPermittedIdentifiers</key>29<array>30 <string>com.example.app.refresh</string>31 <string>com.example.app.db-cleanup</string>32 <string>com.example.app.export.*</string>33</array>34<key>UIBackgroundModes</key>35<array>36 <string>fetch</string> <!-- Required for BGAppRefreshTask -->37 <string>processing</string> <!-- Required for BGProcessingTask -->38 <string>remote-notification</string> <!-- Required for silent push -->39</array>40```4142In Xcode: Target > Signing & Capabilities > Background Modes > enable **Background fetch**, **Background processing**, or **Remote notifications**.4344## Task Selection Matrix4546| Task Type | Max Duration | Trigger | Requires Power/Network | Use Case |47|---|---|---|---|---|48| `BGAppRefreshTask` | ~30 seconds | System opportunistic | Configurable hint | Light feed/state updates |49| `BGProcessingTask` | Several minutes | Device idle | External power / network optional | Database cleanup, maintenance, ML indexing |50| `BGContinuedProcessingTask` | User bounded | Foreground user action | Live Activity progress | Exporting large media, offline bundle generation |51| `URLSession.background` | Managed out-of-process | Network completion | Cellular/WiFi policy | Large file downloads and uploads |52| Silent Remote Push | ~30 seconds | APNs trigger (`content-available: 1`) | Network required | Server-driven data invalidation hint |5354## Core Lifecycle Rules55561. **Register before launch finishes**: Register all handlers in `application(_:didFinishLaunchingWithOptions:)` (UIKit) or `App.init()` (SwiftUI). Submitting an unregistered identifier throws runtime exceptions.572. **Re-schedule inside handler**: Immediately schedule the next iteration at the beginning of the execution handler so scheduling survives app crashes or task timeouts.583. **Always set `expirationHandler`**: The system can revoke background execution time at any moment. The expiration handler must cancel active tasks and call `setTaskCompleted(success: false)`.594. **Call `setTaskCompleted(success:)` exactly once**: Failing to call completion causes the system to penalize future execution allocations.605. **Treat `earliestBeginDate` as a lower bound**: iOS determines actual launch time based on battery status, power state, and user interaction patterns.6162## Route by Task6364- For full registration code, canonical handlers, and checkpointing, read [Canonical Registration and Handlers](references/background-task-patterns.md#canonical-bgtaskscheduler-registration).65- For simulating task launches with LLDB (`_simulateLaunchForTaskWithIdentifier:`), read [Debugging Background Tasks](references/background-task-patterns.md#debugging-background-tasks).66- For background downloads, uploads, and handling app relaunch in `handleEventsForBackgroundURLSession`, read [Background URLSession Extended Patterns](references/background-task-patterns.md#background-urlsession--extended-patterns).67- For background push throttling and payload constraints, read [Background Push Extended Patterns](references/background-task-patterns.md#background-push--extended-patterns).68- For continued processing tasks conforming to `ProgressReporting`, read [BGContinuedProcessingTask Patterns](references/background-task-patterns.md#bgcontinuedprocessingtask--extended-patterns).6970## iOS 27 Updates7172- Background Neural Engine access is restricted, like GPU limits. Background inference needs the entitlement `com.apple.developer.background-tasks.continued-processing.inference`.73- `UIScene.extendStateRestoration` and `UIScene.completeStateRestoration` extend state restoration across background-to-foreground transitions.74- Apps built with the iOS 27 SDK must use the scene-based life cycle or they fail to launch.75- On Demand Resources and `NSBundleResourceRequest` are deprecated; use Background Assets. Background Assets adds localized asset packs, delivered by the user's preferred languages.7677Sources: https://sosumi.ai/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes7879## Common Mistakes8081- Submitting a task identifier that is not declared in `BGTaskSchedulerPermittedIdentifiers` (throws `.notPermitted`).82- Forgetting to call `task.setTaskCompleted(success:)` on all execution and failure paths.83- Omitting `task.expirationHandler`, leading to watchdog termination when background time expires.84- Scheduling app refresh at aggressive minute-scale intervals instead of respecting system heuristics.85- Using async/await convenience APIs or completion closures on background `URLSession` (requires delegate).8687## Review Checklist8889- [ ] Task identifiers declared in `BGTaskSchedulerPermittedIdentifiers`90- [ ] Required `UIBackgroundModes` enabled (`fetch`, `processing`, `remote-notification`)91- [ ] Handlers registered during app launch before launch completes92- [ ] `expirationHandler` cancels active tasks and reports failure93- [ ] `setTaskCompleted(success:)` called exactly once on all code paths94- [ ] Subsequent tasks re-scheduled within the handler95- [ ] Background `URLSession` uses delegate and preserves background completion handler96- [ ] Downloaded files moved in `urlSession(_:downloadTask:didFinishDownloadingTo:)` before return97- [ ] Silent pushes include `content-available: 1`, `apns-push-type: background`, and priority 59899## References100101- [Background task patterns and debugging recipes](references/background-task-patterns.md)102- [BGTaskScheduler](https://sosumi.ai/documentation/backgroundtasks/bgtaskscheduler)103- [BGAppRefreshTask](https://sosumi.ai/documentation/backgroundtasks/bgapprefreshtask)104- [BGProcessingTask](https://sosumi.ai/documentation/backgroundtasks/bgprocessingtask)105- [BGContinuedProcessingTask](https://sosumi.ai/documentation/backgroundtasks/bgcontinuedprocessingtask)106- [Performing long-running tasks on iOS and iPadOS](https://sosumi.ai/documentation/backgroundtasks/performing-long-running-tasks-on-ios-and-ipados)