CtrlK
BlogDocsLog inGet started
Tessl Logo

dpearson2699/swift-ios-skills

Agent skills for iOS, iPadOS, Swift, SwiftUI, and modern Apple framework development.

71

Quality

89%

Does it follow best practices?

Impact

—

No eval scenarios have been run

SecuritybySnyk

Advisory

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

background-task-patterns.mdskills/background-processing/references/

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
  • Advanced BGProcessingTask Patterns
  • Background URLSession — Extended Patterns
  • Background Push — Extended Patterns
  • SwiftUI BackgroundTask Modifier
  • 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 in the debugger with a breakpoint hit or paused.

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.refresh"]

For processing tasks:

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.db-cleanup"]

To simulate early termination (expiration):

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.example.app.refresh"]

Verifying Pending Tasks

Check what tasks are currently scheduled:

BGTaskScheduler.shared.getPendingTaskRequests { requests in
    for request in requests {
        print("Pending: \(request.identifier), earliest: \(String(describing: request.earliestBeginDate))")
    }
}

Common Debugging Issues

SymptomCauseFix
Task never firesIdentifier not in Info.plistAdd to BGTaskSchedulerPermittedIdentifiers
Task never firesBackground modes not enabledEnable fetch and/or processing in capabilities
Task never fires on deviceDevice in Low Power ModeLow Power Mode suppresses background tasks
.notPermitted errorIdentifier mismatchVerify exact string match between code and plist
.unavailable errorRunning in extensionBGTaskScheduler not available in app extensions
.tooManyPendingTaskRequestsOver 10 pending refresh or 1 processing per identifierCancel old requests before submitting new ones

Advanced BGProcessingTask Patterns

Conditional Requirements

Use requiresExternalPower and requiresNetworkConnectivity to ensure the system only launches your task when conditions are met:

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:

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

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

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
// 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

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

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:

{
    "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.

Rate Limiting

Apple throttles background push delivery. Guidelines:

  • System limits to a few pushes per hour per app
  • If the user force-quits the app, background pushes stop entirely until next manual launch
  • High-priority pushes (apns-priority: 10) are delivered immediately but must only be used when the notification triggers user-visible content
  • Low-priority pushes (apns-priority: 5) are batched and delivered opportunistically

Handling Push with Async Work

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:

@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 convenience wrapper. Under the hood it registers with BGTaskScheduler. You still need the Info.plist identifiers and background modes.

BGContinuedProcessingTask — Extended Patterns

Checking Supported Resources

Before requesting GPU or other resources, verify the device supports them:

let supported = BGTaskScheduler.shared.supportedResources
if supported.contains(.gpu) {
    request.requiredResources = .gpu
}

Submission Strategies

BGContinuedProcessingTaskRequest.SubmissionStrategy controls behavior when the system cannot run the task immediately:

StrategyBehavior
.queueTask is queued and starts as soon as possible
.failSubmission 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:

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:

// 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)
}

skills

background-processing

references

background-task-patterns.md

SKILL.md

CHANGELOG.md

README.md

tile.json