axiom-background-processing-ref

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

<!-- Required: List all task identifiers -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.yourapp.refresh</string>
    <string>com.yourapp.maintenance</string>
    <!-- Wildcard for dynamic identifiers (iOS 26+) -->
    <string>com.yourapp.export.*</string>
</array>

<!-- Required: Enable background modes -->
<key>UIBackgroundModes</key>
<array>
    <!-- For BGAppRefreshTask -->
    <string>fetch</string>
    <!-- For BGProcessingTask -->
    <string>processing</string>
</array>

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