Background Processing

作者 dpearson26998d90fd121a26无许可证1.1K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

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.

仅含说明Software Development
AI 生成的概览

指导 iOS 后台任务：BGTaskScheduler、后台 URLSession 下载与后台推送通知。

功能
该技能提供在 iOS 上使用 BackgroundTasks 框架注册、调度和执行后台工作的说明与代码模式。内容涵盖 Info.plist 配置、BGAppRefreshTask、BGProcessingTask、iOS 26+ 的 BGContinuedProcessingTask、后台 URLSession 下载以及后台推送触发。它还列出常见错误和审查清单，并指向包含扩展模式与调试指导的参考文件。
适用场景
适用于添加或审查 iOS 后台执行逻辑，例如注册刷新或处理任务、让前台启动的工作在后台继续，或处理后台下载与静默推送。也适合检查 Info.plist 标识符、过期处理和任务完成路径。
运行要求
不附带脚本，仅为说明文档。需要 iOS 或 iPadOS 应用项目、BackgroundTasks 框架以及 Xcode 能力配置；若使用推送触发还需 APNs 设置。参考文件 references/background-task-patterns.md 需与 SKILL.md 配合阅读。

Background Processing

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

Contents

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>

Also enable the required UIBackgroundModes:

xml
<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    }}

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

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

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

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

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}

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

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

Background Push Triggers

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

json
{ "aps": { "content-available": 1 }, "custom-data": "new-messages" }

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

Enable "Remote notifications" in Background Modes and register:

swift
UIApplication.shared.registerForRemoteNotifications()

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>

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

Review Checklist

  • All task identifiers listed in BGTaskSchedulerPermittedIdentifiers
  • Required UIBackgroundModes enabled (fetch, processing)
  • Tasks registered before app launch completes
  • setTaskCompleted(success:) called on every code path
  • expirationHandler set and cancels in-flight work
  • Next task scheduled inside the handler (re-schedule pattern)
  • earliestBeginDate uses reasonable intervals and is treated as a hint
  • Background URLSession uses delegate (not async/closures)
  • Background URLSession file moved in didFinishDownloadingTo before return
  • handleEventsForBackgroundURLSession stores and calls completion handler
  • Background push payload includes content-available: 1
  • Background push APNs request uses apns-push-type: background and apns-priority: 5
  • fetchCompletionHandler called promptly with correct result
  • BGContinuedProcessingTask reports progress via ProgressReporting
  • Work is incremental and cancellation-safe (Task.checkCancellation())
  • No blocking synchronous work in task handlers

References

来源与署名

来源：dpearson2699/swift-ios-skills位于skills/background-processing提交8d90fd1

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 dpearson2699/swift-ios-skills 的技能

Widgetkit

dpearson2699

指导实现、审查和改进 iOS、iPadOS、watchOS 与 CarPlay 上的 WidgetKit 小组件和控制项。

Software Development1.1K2个月前更新

Weatherkit

dpearson2699

指导 iOS 开发者使用 WeatherService 获取 WeatherKit 预报、警报与署名信息。

Software Development1.1K2个月前更新

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.

待分类1.1K2个月前更新

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.

待分类1.1K2个月前更新

Tabletopkit

dpearson2699

指导使用 TabletopKit 在 visionOS 上构建多人空间桌游，涵盖棋具、座位、动作与 RealityKit 渲染。

Software Development1.1K2个月前更新

Swiftui Webkit

dpearson2699

指导在 iOS 26 及更高版本的 SwiftUI 应用中使用 WebKit for SwiftUI 嵌入和控制网页内容。

Software Development1.1K2个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新