SuperAPI AI Directory

background-processing

General & other

View repository

Updated 10-16 05:52

About this skill

Background Processing

Register, schedule, and execute background tasks on iOS using BackgroundTasks (BGTaskScheduler), background URLSession, and background push notifications. Targets Swift 6.3 / iOS 26+.

Contents

  • Capabilities and Configuration
  • Task Selection Matrix
  • Core Lifecycle Rules
  • Route by Task
  • Common Mistakes
  • Review Checklist
  • References

Capabilities and Configuration

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

<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>UIBackgroundModes</key>
<array>
    <string>fetch</string>       <!-- Required for BGAppRefreshTask -->
    <string>processing</string>  <!-- Required for BGProcessingTask -->
    <string>remote-notification</string> <!-- Required for silent push -->
</array>

In Xcode: Target > Signing & Capabilities > Background Modes > enable Background fetch, Background processing, or Remote notifications.

Task Selection Matrix

Task Type Max Duration Trigger Requires Power/Network Use Case
BGAppRefreshTask ~30 seconds System opportunistic Configurable hint Light feed/state updates
BGProcessingTask Several minutes Device idle External power / network optional Database cleanup, maintenance, ML indexing
BGContinuedProcessingTask User bounded Foreground user action Live Activity progress Exporting large media, offline bundle generation
URLSession.background Managed out-of-process Network completion Cellular/WiFi policy Large file downloads and uploads
Silent Remote Push ~30 seconds APNs trigger (content-available: 1) Network required Server-driven data invalidation hint

Core Lifecycle Rules

  1. Register before launch finishes: Register all handlers in application(_:didFinishLaunchingWithOptions:) (UIKit) or App.init() (SwiftUI). Submitting an unregistered identifier throws runtime exceptions.
  2. Re-schedule inside handler: Immediately schedule the next iteration at the beginning of the execution handler so scheduling survives app crashes or task timeouts.
  3. Always set expirationHandler: The system can revoke background execution time at any moment. The expiration handler must cancel active tasks and call setTaskCompleted(success: false).
  4. Call setTaskCompleted(success:) exactly once: Failing to call completion causes the system to penalize future execution allocations.
  5. Treat earliestBeginDate as a lower bound: iOS determines actual launch time based on battery status, power state, and user interaction patterns.

Route by Task

Common Mistakes

  • Submitting a task identifier that is not declared in BGTaskSchedulerPermittedIdentifiers (throws .notPermitted).
  • Forgetting to call task.setTaskCompleted(success:) on all execution and failure paths.
  • Omitting task.expirationHandler, leading to watchdog termination when background time expires.
  • Scheduling app refresh at aggressive minute-scale intervals instead of respecting system heuristics.
  • Using async/await convenience APIs or completion closures on background URLSession (requires delegate).

Review Checklist

  • Task identifiers declared in BGTaskSchedulerPermittedIdentifiers
  • Required UIBackgroundModes enabled (fetch, processing, remote-notification)
  • Handlers registered during app launch before launch completes
  • expirationHandler cancels active tasks and reports failure
  • setTaskCompleted(success:) called exactly once on all code paths
  • Subsequent tasks re-scheduled within the handler
  • Background URLSession uses delegate and preserves background completion handler
  • Downloaded files moved in urlSession(_:downloadTask:didFinishDownloadingTo:) before return
  • Silent pushes include content-available: 1, apns-push-type: background, and priority 5

References