Background Processing

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

Schedule 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.

Instructions onlySoftware Development

AI-generated overview

Guides iOS background work with BGTaskScheduler, background URLSession downloads, and background push notifications.

What it does: This skill provides instructions and code patterns for registering, scheduling, and executing background work on iOS using the BackgroundTasks framework. It covers Info.plist configuration, BGAppRefreshTask, BGProcessingTask, BGContinuedProcessingTask on iOS 26+, background URLSession downloads, and background push triggers. It also lists common mistakes and a review checklist, and points to a reference file with extended patterns and debugging guidance.
When to use it: Use it when adding or reviewing iOS background execution, such as registering refresh or processing tasks, continuing foreground-started work in the background, or handling background downloads and silent push. It is also useful for checking Info.plist identifiers, expiration handling, and task completion paths.
Requirements: No scripts are shipped; it is instructions only. It assumes an iOS or iPadOS app project using the BackgroundTasks framework, Xcode capability configuration, and, for push triggers, APNs setup. The reference file references/background-task-patterns.md is read alongside SKILL.md.

Background Processing

Register, schedule, and execute background work on iOS using the BackgroundTasks framework, background URLSession, and background push notifications.

Info.plist Configuration
BGTaskScheduler Registration
BGAppRefreshTask Patterns
BGProcessingTask Patterns
BGContinuedProcessingTask (iOS 26+)
Background URLSession Downloads
Background Push Triggers
Common Mistakes
Review Checklist
References

Info.plist Configuration

Every task identifier must be declared in Info.plist under BGTaskSchedulerPermittedIdentifiers, or submit(_:) throws BGTaskScheduler.Error.Code.notPermitted.

xml

<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>BGTaskSchedulerPermittedIdentifiers</key><array>    <string>com.example.app.refresh</string>    <string>com.example.app.db-cleanup</string>    <string>com.example.app.export.*</string></array>

Also enable the required UIBackgroundModes:

xml

<key>UIBackgroundModes</key><array>    <string>fetch</string>       <!-- Required for BGAppRefreshTask -->    <string>processing</string>  <!-- Required for BGProcessingTask --></array>

<key>UIBackgroundModes</key><array>    <string>fetch</string>       <!-- Required for BGAppRefreshTask -->    <string>processing</string>  <!-- Required for BGProcessingTask --></array>

In Xcode: target > Signing & Capabilities > Background Modes > enable "Background fetch" and "Background processing".

BGTaskScheduler Registration

Register handlers before app launch completes. In UIKit, register in application(_:didFinishLaunchingWithOptions:); in SwiftUI, register in App.init().

UIKit Registration

swift

import BackgroundTasks
@mainclass AppDelegate: UIResponder, UIApplicationDelegate {    func application(        _ application: UIApplication,        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?    ) -> Bool {        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.refresh",            using: nil  // nil = default background queue        ) { task in            self.handleAppRefresh(task: task as! BGAppRefreshTask)        }
        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.db-cleanup",            using: nil        ) { task in            self.handleDatabaseCleanup(task: task as! BGProcessingTask)        }
        return true    }}

import BackgroundTasks
@mainclass AppDelegate: UIResponder, UIApplicationDelegate {    func application(        _ application: UIApplication,        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?    ) -> Bool {        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.refresh",            using: nil  // nil = default background queue        ) { task in            self.handleAppRefresh(task: task as! BGAppRefreshTask)        }
        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.db-cleanup",            using: nil        ) { task in            self.handleDatabaseCleanup(task: task as! BGProcessingTask)        }
        return true    }}

SwiftUI Registration

swift

import SwiftUIimport BackgroundTasks
@mainstruct MyApp: App {    init() {        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.refresh",            using: nil        ) { task in            BackgroundTaskManager.shared.handleAppRefresh(                task: task as! BGAppRefreshTask            )        }    }
    var body: some Scene {        WindowGroup { ContentView() }    }}

import SwiftUIimport BackgroundTasks
@mainstruct MyApp: App {    init() {        BGTaskScheduler.shared.register(            forTaskWithIdentifier: "com.example.app.refresh",            using: nil        ) { task in            BackgroundTaskManager.shared.handleAppRefresh(                task: task as! BGAppRefreshTask            )        }    }
    var body: some Scene {        WindowGroup { ContentView() }    }}

BGAppRefreshTask Patterns

Short-lived tasks (~30 seconds) for fetching small data updates. The system decides when to launch; earliestBeginDate is only a lower-bound hint.

swift

func scheduleAppRefresh() {    let request = BGAppRefreshTaskRequest(        identifier: "com.example.app.refresh"    )    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not schedule app refresh: \(error)")    }}
func handleAppRefresh(task: BGAppRefreshTask) {    // Schedule the next refresh before doing work    scheduleAppRefresh()
    let fetchTask = Task {        do {            let data = try await APIClient.shared.fetchLatestFeed()            await FeedStore.shared.update(with: data)            task.setTaskCompleted(success: true)        } catch {            task.setTaskCompleted(success: false)        }    }
    // CRITICAL: Handle expiration -- system can revoke time at any moment    task.expirationHandler = {        fetchTask.cancel()        task.setTaskCompleted(success: false)    }}

func scheduleAppRefresh() {    let request = BGAppRefreshTaskRequest(        identifier: "com.example.app.refresh"    )    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not schedule app refresh: \(error)")    }}
func handleAppRefresh(task: BGAppRefreshTask) {    // Schedule the next refresh before doing work    scheduleAppRefresh()
    let fetchTask = Task {        do {            let data = try await APIClient.shared.fetchLatestFeed()            await FeedStore.shared.update(with: data)            task.setTaskCompleted(success: true)        } catch {            task.setTaskCompleted(success: false)        }    }
    // CRITICAL: Handle expiration -- system can revoke time at any moment    task.expirationHandler = {        fetchTask.cancel()        task.setTaskCompleted(success: false)    }}

BGProcessingTask Patterns

Long-running tasks (minutes) for maintenance, data processing, or cleanup. They run while the device is idle and can require external power; the same earliestBeginDate lower-bound rule applies.

swift

func scheduleProcessingTask() {    let request = BGProcessingTaskRequest(        identifier: "com.example.app.db-cleanup"    )    request.requiresNetworkConnectivity = false    request.requiresExternalPower = true    request.earliestBeginDate = Date(timeIntervalSinceNow: 60 * 60)    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not schedule processing task: \(error)")    }}
func handleDatabaseCleanup(task: BGProcessingTask) {    scheduleProcessingTask()
    let cleanupTask = Task {        do {            try await DatabaseManager.shared.purgeExpiredRecords()            try await DatabaseManager.shared.rebuildIndexes()            task.setTaskCompleted(success: true)        } catch {            task.setTaskCompleted(success: false)        }    }
    task.expirationHandler = {        cleanupTask.cancel()        task.setTaskCompleted(success: false)    }}

func scheduleProcessingTask() {    let request = BGProcessingTaskRequest(        identifier: "com.example.app.db-cleanup"    )    request.requiresNetworkConnectivity = false    request.requiresExternalPower = true    request.earliestBeginDate = Date(timeIntervalSinceNow: 60 * 60)    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not schedule processing task: \(error)")    }}
func handleDatabaseCleanup(task: BGProcessingTask) {    scheduleProcessingTask()
    let cleanupTask = Task {        do {            try await DatabaseManager.shared.purgeExpiredRecords()            try await DatabaseManager.shared.rebuildIndexes()            task.setTaskCompleted(success: true)        } catch {            task.setTaskCompleted(success: false)        }    }
    task.expirationHandler = {        cleanupTask.cancel()        task.setTaskCompleted(success: false)    }}

BGContinuedProcessingTask (iOS 26+)

A task initiated in the foreground by a user action that continues running in the background. The system displays progress via a Live Activity. Conforms to ProgressReporting.

Availability: iOS 26.0+, iPadOS 26.0+

Unlike BGAppRefreshTask and BGProcessingTask, this task starts immediately from the foreground. The system can terminate it under resource pressure, prioritizing tasks that report minimal progress first. Set expirationHandler for user or system cancellation, cancel in-flight work, and clean up partial output before reporting completion.

swift

import BackgroundTasks
func startExport() {    // Register the task handler at app launch, not here.    // BGTaskScheduler requires registration before app launch completes.    let jobID = UUID().uuidString    let request = BGContinuedProcessingTaskRequest(        identifier: "com.example.app.export.\(jobID)",        title: "Exporting Photos",        subtitle: "Processing 247 items"    )    // Use a permitted base wildcard identifier: com.example.app.export.*    // earliestBeginDate is ignored for continued processing requests.    // .queue: begin as soon as possible if can't run immediately    // .fail: fail submission if can't run immediately    request.strategy = .queue
    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not submit continued processing task: \(error)")    }}
func performExport(task: BGContinuedProcessingTask) async {    let items = await PhotoLibrary.shared.itemsToExport()    let progress = task.progress    progress.totalUnitCount = Int64(items.count)
    for (index, item) in items.enumerated() {        if Task.isCancelled { break }
        await PhotoExporter.shared.export(item)        progress.completedUnitCount = Int64(index + 1)
        // Update the user-facing title/subtitle        task.updateTitle(            "Exporting Photos",            subtitle: "\(index + 1) of \(items.count) complete"        )    }
    task.setTaskCompleted(success: !Task.isCancelled)}

import BackgroundTasks
func startExport() {    // Register the task handler at app launch, not here.    // BGTaskScheduler requires registration before app launch completes.    let jobID = UUID().uuidString    let request = BGContinuedProcessingTaskRequest(        identifier: "com.example.app.export.\(jobID)",        title: "Exporting Photos",        subtitle: "Processing 247 items"    )    // Use a permitted base wildcard identifier: com.example.app.export.*    // earliestBeginDate is ignored for continued processing requests.    // .queue: begin as soon as possible if can't run immediately    // .fail: fail submission if can't run immediately    request.strategy = .queue
    do {        try BGTaskScheduler.shared.submit(request)    } catch {        print("Could not submit continued processing task: \(error)")    }}
func performExport(task: BGContinuedProcessingTask) async {    let items = await PhotoLibrary.shared.itemsToExport()    let progress = task.progress    progress.totalUnitCount = Int64(items.count)
    for (index, item) in items.enumerated() {        if Task.isCancelled { break }
        await PhotoExporter.shared.export(item)        progress.completedUnitCount = Int64(index + 1)
        // Update the user-facing title/subtitle        task.updateTitle(            "Exporting Photos",            subtitle: "\(index + 1) of \(items.count) complete"        )    }
    task.setTaskCompleted(success: !Task.isCancelled)}

For GPU work, check support and enable Background GPU Access (com.apple.developer.background-tasks.continued-processing.gpu):

swift

let supported = BGTaskScheduler.supportedResourcesif supported.contains(.gpu) {    request.requiredResources = .gpu}

let supported = BGTaskScheduler.supportedResourcesif supported.contains(.gpu) {    request.requiredResources = .gpu}

Background URLSession Downloads

Use URLSessionConfiguration.background for downloads that continue even after the app is suspended or terminated. The system handles the transfer out of process.

swift

class DownloadManager: NSObject, URLSessionDownloadDelegate {    static let shared = DownloadManager()
    private lazy var session: URLSession = {        let config = URLSessionConfiguration.background(            withIdentifier: "com.example.app.background-download"        )        config.isDiscretionary = true        config.sessionSendsLaunchEvents = true        return URLSession(configuration: config, delegate: self, delegateQueue: nil)    }()
    func startDownload(from url: URL) {        let task = session.downloadTask(with: url)        task.earliestBeginDate = Date(timeIntervalSinceNow: 60)        task.resume()    }
    func urlSession(        _ session: URLSession,        downloadTask: URLSessionDownloadTask,        didFinishDownloadingTo location: URL    ) {        // Move file from tmp before this method returns        let dest = FileManager.default.urls(            for: .documentDirectory, in: .userDomainMask        )[0].appendingPathComponent("download.dat")        try? FileManager.default.moveItem(at: location, to: dest)    }
    func urlSession(        _ session: URLSession,        task: URLSessionTask,        didCompleteWithError error: (any Error)?    ) {        if let error { print("Download failed: \(error)") }    }}

class DownloadManager: NSObject, URLSessionDownloadDelegate {    static let shared = DownloadManager()
    private lazy var session: URLSession = {        let config = URLSessionConfiguration.background(            withIdentifier: "com.example.app.background-download"        )        config.isDiscretionary = true        config.sessionSendsLaunchEvents = true        return URLSession(configuration: config, delegate: self, delegateQueue: nil)    }()
    func startDownload(from url: URL) {        let task = session.downloadTask(with: url)        task.earliestBeginDate = Date(timeIntervalSinceNow: 60)        task.resume()    }
    func urlSession(        _ session: URLSession,        downloadTask: URLSessionDownloadTask,        didFinishDownloadingTo location: URL    ) {        // Move file from tmp before this method returns        let dest = FileManager.default.urls(            for: .documentDirectory, in: .userDomainMask        )[0].appendingPathComponent("download.dat")        try? FileManager.default.moveItem(at: location, to: dest)    }
    func urlSession(        _ session: URLSession,        task: URLSessionTask,        didCompleteWithError error: (any Error)?    ) {        if let error { print("Download failed: \(error)") }    }}

Handle app relaunch — store and invoke the system completion handler:

swift

// In AppDelegate:func application(    _ application: UIApplication,    handleEventsForBackgroundURLSession identifier: String,    completionHandler: @escaping () -> Void) {    backgroundSessionCompletionHandler = completionHandler}
// In URLSessionDelegate — call stored handler when events finish:func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {    Task { @MainActor in        self.backgroundSessionCompletionHandler?()        self.backgroundSessionCompletionHandler = nil    }}

// In AppDelegate:func application(    _ application: UIApplication,    handleEventsForBackgroundURLSession identifier: String,    completionHandler: @escaping () -> Void) {    backgroundSessionCompletionHandler = completionHandler}
// In URLSessionDelegate — call stored handler when events finish:func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {    Task { @MainActor in        self.backgroundSessionCompletionHandler?()        self.backgroundSessionCompletionHandler = nil    }}

Background Push Triggers

Silent push notifications wake your app briefly to fetch new content. Set content-available: 1 in the push payload.

Send the APNs request with apns-push-type: background and apns-priority: 5. Background push delivery is low priority and not guaranteed; keep sends infrequent, generally no more than two or three per hour.

Handle in AppDelegate:

swift

func application(    _ application: UIApplication,    didReceiveRemoteNotification userInfo: [AnyHashable: Any],    fetchCompletionHandler completionHandler:        @escaping (UIBackgroundFetchResult) -> Void) {    Task {        do {            let hasNew = try await MessageStore.shared.fetchNewMessages()            completionHandler(hasNew ? .newData : .noData)        } catch {            completionHandler(.failed)        }    }}

func application(    _ application: UIApplication,    didReceiveRemoteNotification userInfo: [AnyHashable: Any],    fetchCompletionHandler completionHandler:        @escaping (UIBackgroundFetchResult) -> Void) {    Task {        do {            let hasNew = try await MessageStore.shared.fetchNewMessages()            completionHandler(hasNew ? .newData : .noData)        } catch {            completionHandler(.failed)        }    }}

Enable "Remote notifications" in Background Modes and register:

Common Mistakes

1. Missing Info.plist identifiers

swift

// DON'T: Submit a task whose identifier isn't in BGTaskSchedulerPermittedIdentifierslet request = BGAppRefreshTaskRequest(identifier: "com.example.app.refresh")try BGTaskScheduler.shared.submit(request)  // Throws .notPermitted
// DO: Add every identifier to Info.plist BGTaskSchedulerPermittedIdentifiers// <string>com.example.app.refresh</string>

// DON'T: Submit a task whose identifier isn't in BGTaskSchedulerPermittedIdentifierslet request = BGAppRefreshTaskRequest(identifier: "com.example.app.refresh")try BGTaskScheduler.shared.submit(request)  // Throws .notPermitted
// DO: Add every identifier to Info.plist BGTaskSchedulerPermittedIdentifiers// <string>com.example.app.refresh</string>

2. Not calling setTaskCompleted(success:)

Use the canonical app-refresh or processing handler above: every success, failure, and cancellation path reports completion exactly once.

3. Ignoring the expiration handler

Use the same canonical handler to cancel in-flight work and report failure from expirationHandler.

4. Scheduling too frequently

The scheduling sections own the lower-bound rule. Avoid minute-scale refresh requests; the system still chooses actual launch time.

5. Over-relying on background time

swift

// DON'T: Start a 10-minute operation assuming it will finishfunc handleRefresh(task: BGAppRefreshTask) {    Task { await tenMinuteSync() }}
// DO: Design work to be incremental and cancellablefunc handleRefresh(task: BGAppRefreshTask) {    let work = Task {        for batch in batches {            try Task.checkCancellation()            await processBatch(batch)            await saveBatchProgress(batch)        }        task.setTaskCompleted(success: true)    }    task.expirationHandler = {        work.cancel()        task.setTaskCompleted(success: false)    }}

// DON'T: Start a 10-minute operation assuming it will finishfunc handleRefresh(task: BGAppRefreshTask) {    Task { await tenMinuteSync() }}
// DO: Design work to be incremental and cancellablefunc handleRefresh(task: BGAppRefreshTask) {    let work = Task {        for batch in batches {            try Task.checkCancellation()            await processBatch(batch)            await saveBatchProgress(batch)        }        task.setTaskCompleted(success: true)    }    task.expirationHandler = {        work.cancel()        task.setTaskCompleted(success: false)    }}

Review Checklist

References

See references/background-task-patterns.md [blocked] for extended patterns, background URLSession edge cases, debugging with simulated launches, and background push best practices.
BGTaskScheduler
BGAppRefreshTask
BGProcessingTask
BGContinuedProcessingTask (iOS 26+)
BGContinuedProcessingTaskRequest (iOS 26+)
Using background tasks to update your app
Performing long-running tasks on iOS and iPadOS

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/background-processingat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Background Processing

Background Processing

Contents

Info.plist Configuration

BGTaskScheduler Registration

UIKit Registration

SwiftUI Registration

BGAppRefreshTask Patterns

BGProcessingTask Patterns

BGContinuedProcessingTask (iOS 26+)

Background URLSession Downloads

Background Push Triggers

Common Mistakes

1. Missing Info.plist identifiers

2. Not calling setTaskCompleted(success:)

3. Ignoring the expiration handler

4. Scheduling too frequently

5. Over-relying on background time

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices