Background Processing Reference
Complete API reference for iOS background execution, with code examples from WWDC sessions.
Related skills: axiom-background-processing (decision trees, patterns), axiom-background-processing-diag (troubleshooting)
Part 1: BGTaskScheduler Registration Info.plist Configuration
Register Handler import BackgroundTasks
func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool {
// Register BEFORE returning from didFinishLaunching
BGTaskScheduler.shared.register(
forTaskWithIdentifier: "com.yourapp.refresh",
using: nil // nil = system creates serial background queue
) { task in
self.handleAppRefresh(task: task as! BGAppRefreshTask)
}
BGTaskScheduler.shared.register(
forTaskWithIdentifier: "com.yourapp.maintenance",
using: nil
) { task in
self.handleMaintenance(task: task as! BGProcessingTask)
}
return true
}
Parameters:
forTaskWithIdentifier: Must match Info.plist exactly (case-sensitive) using: DispatchQueue for handler callback; nil = system creates one launchHandler: Called when task is launched; receives BGTask subclass Registration Timing
From WWDC 2019-707:
"You do this by registering a launch handler before your application finishes launching"
Register in:
✅ application(_:didFinishLaunchingWithOptions:) before return true ❌ Not in viewDidLoad, button handlers, or async callbacks Part 2: BGAppRefreshTask Purpose
Keep app content fresh throughout the day. System launches app based on user usage patterns.
Runtime
~30 seconds (same as legacy background fetch)
Scheduling func scheduleAppRefresh() { let request = BGAppRefreshTaskRequest(identifier: "com.yourapp.refresh")
// earliestBeginDate = MINIMUM delay (not exact time)
// System decides actual time based on usage patterns
request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
do {
try BGTaskScheduler.shared.submit(request)
} catch BGTaskScheduler.Error.notPermitted {
// Background App Refresh disabled in Settings
} catch BGTaskScheduler.Error.tooManyPendingTaskRequests {
// Too many pending requests for this identifier
} catch BGTaskScheduler.Error.unavailable {
// Background tasks not available (Simulator, etc.)
} catch {
print("Schedule failed: \(error)")
}
}
// Schedule when app enters background func applicationDidEnterBackground(_ application: UIApplication) { scheduleAppRefresh() }
Handler func handleAppRefresh(task: BGAppRefreshTask) { // 1. Set expiration handler FIRST task.expirationHandler = { [weak self] in self?.currentOperation?.cancel() }
// 2. Schedule NEXT refresh (continuous pattern)
scheduleAppRefresh()
// 3. Perform work
let operation = fetchLatestContentOperation()
currentOperation = operation
operation.completionBlock = {
// 4. Signal completion (REQUIRED)
task.setTaskCompleted(success: !operation.isCancelled)
}
operationQueue.addOperation(operation)
}
BGAppRefreshTaskRequest Properties Property Type Description identifier String Must match Info.plist earliestBeginDate Date? Minimum delay before execution Part 3: BGProcessingTask Purpose
Deferrable maintenance work (database cleanup, ML training, backups). Runs at system-friendly times, typically overnight when charging.
Runtime
Several minutes (significantly longer than refresh tasks)
Scheduling with Constraints func scheduleMaintenanceIfNeeded() { // Only schedule if work is needed guard Date().timeIntervalSince(lastMaintenanceDate) > 7 * 24 * 3600 else { return }
let request = BGProcessingTaskRequest(identifier: "com.yourapp.maintenance")
// CRITICAL for CPU-intensive work
request.requiresExternalPower = true
// Optional: Need network for cloud sync
request.requiresNetworkConnectivity = true
// Keep within 1 week — longer may be skipped
// request.earliestBeginDate = ...
do {
try BGTaskScheduler.shared.submit(request)
} catch {
print("Schedule failed: \(error)")
}
}
Handler with Progress Checkpointing func handleMaintenance(task: BGProcessingTask) { var shouldContinue = true
task.expirationHandler = {
shouldContinue = false
}
Task {
for item in workItems {
guard shouldContinue else {
// Expiration called — save progress and exit
saveProgress()
break
}
await processItem(item)
saveProgress() // Checkpoint after each item
}
task.setTaskCompleted(success: shouldContinue)
}
}
BGProcessingTaskRequest Properties Property Type Default Description identifier String — Must match Info.plist earliestBeginDate Date? nil Minimum delay requiresNetworkConnectivity Bool false Wait for network requiresExternalPower Bool false Wait for charging CPU Monitor Disabling
"For the first time ever, we're giving you the ability to turn that off for the duration of your processing task so you can take full advantage of the hardware while the device is plugged in."
When requiresExternalPower = true, CPU Monitor (which normally terminates CPU-heavy background apps) is disabled.
Part 4: BGContinuedProcessingTask (iOS 26+) Purpose
Continue user-initiated work after app backgrounds, with system UI showing progress. From WWDC 2025-227.
NOT for: Automatic tasks, maintenance, syncing — user must explicitly initiate.
Use Cases
Photo/video export
Publishing content
Updating connected accessories
File compression
Info.plist (Wildcard Pattern)
Dynamic Registration
Unlike other tasks, register when user initiates action:
func userTappedExportButton() { // Register dynamically BGTaskScheduler.shared.register( forTaskWithIdentifier: "com.yourapp.export.photos" ) { task in let continuedTask = task as! BGContinuedProcessingTask self.handleExport(task: continuedTask) }
// Submit immediately
submitExportRequest()
}
Submission with Progress UI func submitExportRequest() { let request = BGContinuedProcessingTaskRequest( identifier: "com.yourapp.export.photos", title: "Exporting Photos", // Shown in system UI subtitle: "0 of 100 photos complete" // Shown in system UI )
// Strategy: .fail = reject if can't start now; .enqueue = queue (default)
request.strategy = .fail
do {
try BGTaskScheduler.shared.submit(request)
} catch {
// Show error — can't run in background now
showError("Cannot export in background right now")
}
}
Handler with Mandatory Progress Reporting func handleExport(task: BGContinuedProcessingTask) { var shouldContinue = true
task.expirationHandler = {
shouldContinue = false
}
// MANDATORY: Report progress
// Tasks with no progress updates are AUTO-EXPIRED
task.progress.totalUnitCount = Int64(photos.count)
task.progress.completedUnitCount = 0
Task {
for (index, photo) in photos.enumerated() {
guard shouldContinue else { break }
await exportPhoto(photo)
// Update progress — system displays to user
task.progress.completedUnitCount = Int64(index + 1)
}
task.setTaskCompleted(success: shouldContinue)
}
}
BGContinuedProcessingTaskRequest Properties Property Type Description identifier String With wildcard, can have dynamic suffix title String Shown in system progress UI subtitle String Shown in system progress UI strategy Strategy .fail or .enqueue (default) Strategy Options // .fail — Reject if can't start immediately request.strategy = .fail
// .enqueue — Queue if can't start (default) // Task may run later
GPU Access (iOS 26+) // Check if GPU available for background task let supportedResources = BGTaskScheduler.shared.supportedResources if supportedResources.contains(.gpu) { // GPU is available }
Part 5: beginBackgroundTask Purpose
Finish critical work (~30 seconds) when app transitions to background. For state saving, completing uploads.
Basic Pattern var backgroundTaskID: UIBackgroundTaskIdentifier = .invalid
func applicationDidEnterBackground(_ application: UIApplication) { backgroundTaskID = application.beginBackgroundTask(withName: "Save State") { // Expiration handler — clean up immediately self.saveProgress() application.endBackgroundTask(self.backgroundTaskID) self.backgroundTaskID = .invalid }
// Do critical work
saveEssentialState { [weak self] in
guard let self = self,
self.backgroundTaskID != .invalid else { return }
// End task AS SOON AS work completes
UIApplication.shared.endBackgroundTask(self.backgroundTaskID)
self.backgroundTaskID = .invalid
}
}
Key Points Call endBackgroundTask immediately when done — don't wait for expiration Failing to end may cause system to terminate app ~30 seconds max, not guaranteed Use for finalization, not ongoing work SwiftUI / SceneDelegate .onChange(of: scenePhase) { newPhase in if newPhase == .background { startBackgroundTask() } }
Part 6: Background URLSession Purpose
Large downloads/uploads that continue even after app termination. Work handed off to system daemon.
Configuration lazy var backgroundSession: URLSession = { let config = URLSessionConfiguration.background( withIdentifier: "com.yourapp.downloads" )
// App relaunched when task completes
config.sessionSendsLaunchEvents = true
// System chooses optimal time (WiFi, charging)
config.isDiscretionary = true
// Timeout for requests (not the download itself)
config.timeoutIntervalForRequest = 60
return URLSession(configuration: config, delegate: self, delegateQueue: nil)
}()
Starting Download func downloadFile(from url: URL) { let task = backgroundSession.downloadTask(with: url) task.resume() // Work continues even if app terminates }
AppDelegate Handler var backgroundSessionCompletionHandler: (() -> Void)?
func application( _ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void ) { // Store — call after all events processed backgroundSessionCompletionHandler = completionHandler }
URLSessionDelegate Implementation extension AppDelegate: URLSessionDelegate, URLSessionDownloadDelegate {
func urlSession(
_ session: URLSession,
downloadTask: URLSessionDownloadTask,
didFinishDownloadingTo location: URL
) {
// MUST move file immediately — temp location deleted after return
let destination = getDestinationURL(for: downloadTask)
try? FileManager.default.moveItem(at: location, to: destination)
}
func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
// All events processed — call stored completion handler
DispatchQueue.main.async {
self.backgroundSessionCompletionHandler?()
self.backgroundSessionCompletionHandler = nil
}
}
}
Configuration Properties Property Default Description sessionSendsLaunchEvents false Relaunch app on completion isDiscretionary false Wait for optimal conditions allowsCellularAccess true Allow cellular network allowsExpensiveNetworkAccess true Allow expensive networks allowsConstrainedNetworkAccess true Allow Low Data Mode Part 7: Testing Background Tasks LLDB Debugging Commands
Pause app in debugger, then execute:
// Trigger task launch e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.yourapp.refresh"]
// Trigger task expiration e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.yourapp.refresh"]
Testing Workflow Set breakpoint in task handler Run app, let it enter background Pause execution (Debug → Pause) Execute simulate launch command Resume — breakpoint should hit Test expiration handling with simulate expiration Console Logging
Filter Console.app:
subsystem:com.apple.backgroundtaskscheduler
getPendingTaskRequests
Check what's scheduled:
BGTaskScheduler.shared.getPendingTaskRequests { requests in for request in requests { print("Pending: (request.identifier)") print(" Earliest: (request.earliestBeginDate ?? Date())") } }
Part 8: Throttling & System Constraints The 7 Scheduling Factors Factor How to Check Impact Critically Low Battery Battery < ~20% Discretionary work paused Low Power Mode ProcessInfo.isLowPowerModeEnabled Limited activity App Usage User opens app frequently? Higher priority App Switcher Not swiped away? Swiped = no background Background App Refresh backgroundRefreshStatus Off = no BGAppRefresh System Budgets Many recent launches? Budget depletes, refills daily Rate Limiting Requests too frequent? System spaces launches Checking Constraints // Low Power Mode if ProcessInfo.processInfo.isLowPowerModeEnabled { // Reduce background work }
// Listen for changes NotificationCenter.default.publisher(for: .NSProcessInfoPowerStateDidChange) .sink { _ in // Adapt behavior }
// Background App Refresh status switch UIApplication.shared.backgroundRefreshStatus { case .available: // Can schedule tasks case .denied: // User disabled — prompt in Settings case .restricted: // MDM or parental controls — cannot enable @unknown default: break }
Thermal State switch ProcessInfo.processInfo.thermalState { case .nominal: break // Normal operation case .fair: // Reduce intensive work case .serious: // Minimize all background activity case .critical: // Stop non-essential work immediately @unknown default: break }
NotificationCenter.default.publisher(for: ProcessInfo.thermalStateDidChangeNotification) .sink { _ in // Respond to thermal changes }
Part 9: Push Notifications for Background Silent Push Payload { "aps": { "content-available": 1 }, "custom-data": "your-payload" }
APNS Priority apns-priority: 5 // Discretionary — energy efficient (recommended) apns-priority: 10 // Immediate — only for time-sensitive
Handler func application( _ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void ) { guard userInfo["aps"] as? [String: Any] != nil else { completionHandler(.noData) return }
Task {
do {
let hasNewData = try await fetchLatestData()
completionHandler(hasNewData ? .newData : .noData)
} catch {
completionHandler(.failed)
}
}
}
Rate Limiting Behavior
"Receiving 14 pushes in a window may result in only 7 launches, maintaining a ~15-minute interval."
Silent pushes are rate-limited. Don't expect launch on every push.
Part 10: SwiftUI Integration backgroundTask Modifier @main struct MyApp: App { @Environment(.scenePhase) var scenePhase
var body: some Scene {
WindowGroup {
ContentView()
}
.onChange(of: scenePhase) { newPhase in
if newPhase == .background {
scheduleAppRefresh()
}
}
// App refresh handler
.backgroundTask(.appRefresh("com.yourapp.refresh")) {
scheduleAppRefresh() // Schedule next
await fetchLatestContent()
// Task completes when closure returns (no setTaskCompleted needed)
}
// Background URLSession handler
.backgroundTask(.urlSession("com.yourapp.downloads")) {
await processDownloadedFiles()
}
}
}
Cancellation with Swift Concurrency .backgroundTask(.appRefresh("com.yourapp.refresh")) { await withTaskCancellationHandler { // Normal work try await fetchData() } onCancel: { // Called when task expires // Keep lightweight — runs synchronously } }
Background URLSession with SwiftUI .backgroundTask(.urlSession("com.yourapp.weather")) { // Called when background URLSession completes // Handle completed downloads }
Quick Reference
Task Types
Type Runtime API Use Case
BGAppRefreshTask ~30s submit(BGAppRefreshTaskRequest) Fresh content
BGProcessingTask Minutes submit(BGProcessingTaskRequest) Maintenance
BGContinuedProcessingTask Extended submit(BGContinuedProcessingTaskRequest) User-initiated
beginBackgroundTask ~30s beginBackgroundTask(withName:) State saving
Background URLSession As needed URLSessionConfiguration.background Downloads
Silent Push ~30s didReceiveRemoteNotification Server trigger
Required Info.plist
LLDB Commands // Launch e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"ID"]
// Expire e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"ID"]
Resources
WWDC: 2019-707, 2020-10063, 2022-10142, 2023-10170, 2025-227
Docs: /backgroundtasks, /backgroundtasks/bgtaskscheduler, /foundation/urlsessionconfiguration
Skills: axiom-background-processing, axiom-background-processing-diag
Last Updated: 2025-12-31 Platforms: iOS 13+, iOS 26+ (BGContinuedProcessingTask)