dpearson2699/swift-ios-skills / skills/background-processing
background-processing
VerifiedSchedule and execute background work on iOS using BGTaskScheduler. Use when registering BGAppRefreshTask for short background fetches, BGProcessingTask for long-running maintenance, BGContinuedProcessingTask (iOS 26+) for foreground-started work that continues in background, background URLSession downloads, or background push notifications. Covers Info.plist configuration, expiration handling, task completion, and debugging with simulated launches.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.7 KB |
| evals/evals.json | config | 3.3 KB |
| references/background-task-patterns.md | markdown | 12.3 KB |
references/background-task-patterns.md
View on GitHub# Background Task Patterns — Extended Reference
Overflow reference for the background-processing skill. Contains debugging tips,
advanced background URLSession patterns, background push best practices, and
SwiftUI integration patterns.
## Contents
- [Debugging Background Tasks](#debugging-background-tasks)
- [Advanced BGProcessingTask Patterns](#advanced-bgprocessingtask-patterns)
- [Background URLSession — Extended Patterns](#background-urlsession--extended-patterns)
- [Background Push — Extended Patterns](#background-push--extended-patterns)
- [SwiftUI BackgroundTask Modifier](#swiftui-backgroundtask-modifier)
- [BGContinuedProcessingTask — Extended Patterns](#bgcontinuedprocessingtask--extended-patterns)
## Debugging Background Tasks
### Simulating Task Launches in Xcode
Use the LLDB console to trigger tasks instantly during development. The app must
be running on a device in the debugger with a breakpoint hit or paused.
These are Apple-documented private functions for development only. Do not
include references to them in App Store-submitted code.
```swift
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.refresh"]
```
For processing tasks:
```swift
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.db-cleanup"]
```
To simulate early termination (expiration):
```swift
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.example.app.refresh"]
```
### Verifying Pending Tasks
Check what tasks are currently scheduled:
```swift
BGTaskScheduler.shared.getPendingTaskRequests { requests in
for request in requests {
print("Pending: \(request.identifier), earliest: \(String(describing: request.earliestBeginDate))")
}
}
```
### Common Debugging Issues
| Symptom | Cause | Fix |
|---|---|---|
| Task never fires | Identifier not in Info.plist | Add to `BGTaskSchedulerPermittedIdentifiers` |
| Task never fires | Background modes not enabled | Enable `fetch` and/or `processing` in capabilities |
| Task never fires on device | Background App Refresh disabled or Low Power Mode active | Check `UIApplication.shared.backgroundRefreshStatus`; Low Power Mode reduces background runtime |
| `.notPermitted` error | Identifier mismatch | Verify exact string match between code and plist |
| `.unavailable` error | Running in extension | BGTaskScheduler not available in app extensions |
| `.tooManyPendingTaskRequests` | More than 1 refresh task or 10 processing tasks scheduled in total | Cancel old requests before submitting new ones |
Submitting an unexecuted task request with the same identifier replaces the
previous request.
## Advanced BGProcessingTask Patterns
### Conditional Requirements
Use `requiresExternalPower` and `requiresNetworkConnectivity` to ensure the
system only launches your task when conditions are met:
```swift
func scheduleSyncTask() {
let request = BGProcessingTaskRequest(
identifier: "com.example.app.full-sync"
)
// Only run when charging and connected to network
request.requiresExternalPower = true
request.requiresNetworkConnectivity = true
// Don't run before 2 AM
var components = DateComponents()
components.hour = 2
if let twoAM = Calendar.current.nextDate(
after: Date(),
matching: components,
matchingPolicy: .nextTime
) {
request.earliestBeginDate = twoAM
}
do {
try BGTaskScheduler.shared.submit(request)
} catch {
print("Failed to schedule sync: \(error)")
}
}
```
### Incremental Work with Checkpointing
Design tasks to save progress so they can resume if terminated:
```swift
func handleMigration(task: BGProcessingTask) {
let work = Task {
let lastProcessed = UserDefaults.standard.integer(
forKey: "migrationLastIndex"
)
let items = try await loadItems()
for (index, item) in items.dropFirst(lastProcessed).enumerated() {
try Task.checkCancellation()
try await migrate(item)
// Checkpoint progress
UserDefaults.standard.set(
lastProcessed + index + 1,
forKey: "migrationLastIndex"
)
}
task.setTaskCompleted(success: true)
}
task.expirationHandler = {
work.cancel()
// Progress is saved -- next launch picks up where we left off
task.setTaskCompleted(success: false)
}
}
```
## Background URLSession — Extended Patterns
### Configuration Best Practices
```swift
let config = URLSessionConfiguration.background(
withIdentifier: "com.example.app.background-transfer"
)
// isDiscretionary = true: system picks optimal time (WiFi, power)
// Use for non-urgent transfers
config.isDiscretionary = true
// sessionSendsLaunchEvents = true: app relaunched when transfer completes
config.sessionSendsLaunchEvents = true
// Set reasonable timeouts
config.timeoutIntervalForResource = 60 * 60 * 24 * 7 // 7 days
// Allow cellular (default is true)
config.allowsCellularAccess = true
```
### Upload with Background Session
```swift
func uploadFile(at fileURL: URL) {
var request = URLRequest(url: URL(string: "https://api.example.com/upload")!)
request.httpMethod = "POST"
let uploadTask = session.uploadTask(with: request, fromFile: fileURL)
uploadTask.resume()
}
```
**Important:** Background sessions only support `uploadTask(with:fromFile:)` and
`downloadTask(with:)`. Data tasks, `uploadTask(with:from:)` (Data), and
closure/async-based tasks are **not** supported.
### Handling App Relaunch
When the system completes a background transfer and your app is not running, it
relaunches the app. You must:
1. Store the completion handler from
`application(_:handleEventsForBackgroundURLSession:completionHandler:)`
2. Recreate the `URLSession` with the **same identifier**
3. Call the stored completion handler in `urlSessionDidFinishEvents`
```swift
// AppDelegate
func application(
_ application: UIApplication,
handleEventsForBackgroundURLSession identifier: String,
completionHandler: @escaping () -> Void
) {
// Recreating session with the same identifier reconnects to the transfer
_ = DownloadManager.shared.session // trigger lazy init
DownloadManager.shared.completionHandler = completionHandler
}
// In your URLSessionDelegate
func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
Task { @MainActor in
self.completionHandler?()
self.completionHandler = nil
}
}
```
### Handling Download Errors and Retries
```swift
func urlSession(
_ session: URLSession,
task: URLSessionTask,
didCompleteWithError error: (any Error)?
) {
guard let error else { return } // Success handled in didFinishDownloadingTo
let nsError = error as NSError
// Check if download can be resumed
if let resumeData = nsError.userInfo[NSURLSessionDownloadTaskResumeData] as? Data {
// Store resumeData and retry later
let downloadTask = session.downloadTask(withResumeData: resumeData)
downloadTask.resume()
return
}
// Non-resumable error -- retry from scratch or notify user
if nsError.code == NSURLErrorNetworkConnectionLost {
// Re-enqueue the download
if let url = task.originalRequest?.url {
let newTask = session.downloadTask(with: url)
newTask.resume()
}
}
}
```
### Progress Tracking
```swift
func urlSession(
_ session: URLSession,
downloadTask: URLSessionDownloadTask,
didWriteData bytesWritten: Int64,
totalBytesWritten: Int64,
totalBytesExpectedToWrite: Int64
) {
let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
// Update UI on main actor if app is in foreground
Task { @MainActor in
DownloadProgressStore.shared.update(
taskID: downloadTask.taskIdentifier,
progress: progress
)
}
}
```
## Background Push — Extended Patterns
### Push Payload Requirements
The `content-available: 1` flag is required. You can include custom data:
```json
{
"aps": {
"content-available": 1
},
"type": "new-message",
"conversation-id": "abc-123"
}
```
**Do not** include `alert`, `badge`, or `sound` if you only want a silent push.
Including visual notification keys changes the push behavior.
Send background notification requests with APNs headers:
```http
apns-push-type: background
apns-priority: 5
```
### Rate Limiting
Apple throttles background push delivery. Guidelines:
- Delivery is low priority and not guaranteed.
- Do not send more than two or three background notifications per hour.
- The system may hold only the newest background notification and discard older
held notifications.
- If the user force-quits the app, background pushes stop until the next manual
launch.
- Use `apns-priority: 5`; high-priority pushes are for user-visible
notifications, not silent refresh.
### Handling Push with Async Work
```swift
func application(
_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable: Any],
fetchCompletionHandler completionHandler:
@escaping (UIBackgroundFetchResult) -> Void
) {
guard let type = userInfo["type"] as? String else {
completionHandler(.noData)
return
}
Task {
do {
switch type {
case "new-message":
let conversationID = userInfo["conversation-id"] as? String
let fetched = try await MessageService.shared
.fetchMessages(for: conversationID)
completionHandler(fetched ? .newData : .noData)
case "config-update":
try await ConfigService.shared.refreshConfig()
completionHandler(.newData)
default:
completionHandler(.noData)
}
} catch {
completionHandler(.failed)
}
}
}
```
**Important:** You have approximately 30 seconds to call `completionHandler`.
Failure to do so causes the system to penalize your app's background push
budget.
## SwiftUI BackgroundTask Modifier
SwiftUI provides a `.backgroundTask` modifier as an alternative to manual
`BGTaskScheduler` registration:
```swift
@main
struct MyApp: App {
var body: some Scene {
WindowGroup { ContentView() }
.backgroundTask(.appRefresh("com.example.app.refresh")) {
await refreshFeed()
// Schedule the next one
scheduleAppRefresh()
}
}
}
```
This is a SwiftUI handler for matching background tasks. You still need the
Info.plist identifiers, background modes, scheduling, and cancellation-safe work
patterns.
## BGContinuedProcessingTask — Extended Patterns
### Checking Supported Resources
Before requesting GPU or other resources, verify the device supports them and
enable Background GPU Access
(`com.apple.developer.background-tasks.continued-processing.gpu`) for GPU work:
```swift
let supported = BGTaskScheduler.supportedResources
if supported.contains(.gpu) {
request.requiredResources = .gpu
}
```
### Submission Strategies
`BGContinuedProcessingTaskRequest.SubmissionStrategy` controls behavior when the
system cannot run the task immediately:
| Strategy | Behavior |
|---|---|
| `.queue` | Task is queued and starts as soon as possible |
| `.fail` | Submission fails immediately if can't run now |
Use `.fail` when the work is only relevant in the current moment (e.g., a user
is waiting). Use `.queue` for work that can start whenever the system allows.
### Cancellation by the User
The system shows a Live Activity for continued processing tasks. The user can
cancel the task from there. Handle this in your expiration handler:
```swift
task.expirationHandler = {
// Clean up partial work
cleanupPartialExport()
task.setTaskCompleted(success: false)
}
```
### Progress Reporting
The system uses your `Progress` object to decide termination priority. Tasks
with no progress updates are terminated first under resource pressure:
```swift
// Report fine-grained progress
let progress = task.progress
progress.totalUnitCount = Int64(totalItems)
for (index, item) in items.enumerated() {
try Task.checkCancellation()
await process(item)
progress.completedUnitCount = Int64(index + 1)
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |