Complete background task API reference - BGTaskScheduler, BGAppRefreshTask, BGProcessingTask, BGContinuedProcessingTask (iOS 26), beginBackgroundTask, background URLSession, with all WWDC code examples
/plugin marketplace add CharlesWiltgen/Axiom/plugin install axiom@axiom-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
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)
<!-- 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>
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 onelaunchHandler: Called when task is launched; receives BGTask subclassFrom WWDC 2019-707:
"You do this by registering a launch handler before your application finishes launching"
Register in:
application(_:didFinishLaunchingWithOptions:) before return trueKeep app content fresh throughout the day. System launches app based on user usage patterns.
~30 seconds (same as legacy background fetch)
func scheduleAppRefresh() {
let request = BGAppRefreshTaskRequest(identifier: "com.yourapp.refresh")
// earliestBeginDate = MINIMUM delay (not exact time)
// System decides actual time based on usage patterns
request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
do {
try BGTaskScheduler.shared.submit(request)
} catch BGTaskScheduler.Error.notPermitted {
// Background App Refresh disabled in Settings
} catch BGTaskScheduler.Error.tooManyPendingTaskRequests {
// Too many pending requests for this identifier
} catch BGTaskScheduler.Error.unavailable {
// Background tasks not available (Simulator, etc.)
} catch {
print("Schedule failed: \(error)")
}
}
// Schedule when app enters background
func applicationDidEnterBackground(_ application: UIApplication) {
scheduleAppRefresh()
}
func handleAppRefresh(task: BGAppRefreshTask) {
// 1. Set expiration handler FIRST
task.expirationHandler = { [weak self] in
self?.currentOperation?.cancel()
}
// 2. Schedule NEXT refresh (continuous pattern)
scheduleAppRefresh()
// 3. Perform work
let operation = fetchLatestContentOperation()
currentOperation = operation
operation.completionBlock = {
// 4. Signal completion (REQUIRED)
task.setTaskCompleted(success: !operation.isCancelled)
}
operationQueue.addOperation(operation)
}
| Property | Type | Description |
|---|---|---|
identifier | String | Must match Info.plist |
earliestBeginDate | Date? | Minimum delay before execution |
Deferrable maintenance work (database cleanup, ML training, backups). Runs at system-friendly times, typically overnight when charging.
Several minutes (significantly longer than refresh tasks)
func scheduleMaintenanceIfNeeded() {
// Only schedule if work is needed
guard Date().timeIntervalSince(lastMaintenanceDate) > 7 * 24 * 3600 else {
return
}
let request = BGProcessingTaskRequest(identifier: "com.yourapp.maintenance")
// CRITICAL for CPU-intensive work
request.requiresExternalPower = true
// Optional: Need network for cloud sync
request.requiresNetworkConnectivity = true
// Keep within 1 week — longer may be skipped
// request.earliestBeginDate = ...
do {
try BGTaskScheduler.shared.submit(request)
} catch {
print("Schedule failed: \(error)")
}
}
func handleMaintenance(task: BGProcessingTask) {
var shouldContinue = true
task.expirationHandler = {
shouldContinue = false
}
Task {
for item in workItems {
guard shouldContinue else {
// Expiration called — save progress and exit
saveProgress()
break
}
await processItem(item)
saveProgress() // Checkpoint after each item
}
task.setTaskCompleted(success: shouldContinue)
}
}
| Property | Type | Default | Description |
|---|---|---|---|
identifier | String | — | Must match Info.plist |
earliestBeginDate | Date? | nil | Minimum delay |
requiresNetworkConnectivity | Bool | false | Wait for network |
requiresExternalPower | Bool | false | Wait for charging |
"For the first time ever, we're giving you the ability to turn that off for the duration of your processing task so you can take full advantage of the hardware while the device is plugged in."
When requiresExternalPower = true, CPU Monitor (which normally terminates CPU-heavy background apps) is disabled.
Continue user-initiated work after app backgrounds, with system UI showing progress. From WWDC 2025-227.
NOT for: Automatic tasks, maintenance, syncing — user must explicitly initiate.
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<!-- Wildcard for dynamic suffix -->
<string>com.yourapp.export.*</string>
</array>
Unlike other tasks, register when user initiates action:
func userTappedExportButton() {
// Register dynamically
BGTaskScheduler.shared.register(
forTaskWithIdentifier: "com.yourapp.export.photos"
) { task in
let continuedTask = task as! BGContinuedProcessingTask
self.handleExport(task: continuedTask)
}
// Submit immediately
submitExportRequest()
}
func submitExportRequest() {
let request = BGContinuedProcessingTaskRequest(
identifier: "com.yourapp.export.photos",
title: "Exporting Photos", // Shown in system UI
subtitle: "0 of 100 photos complete" // Shown in system UI
)
// Strategy: .fail = reject if can't start now; .enqueue = queue (default)
request.strategy = .fail
do {
try BGTaskScheduler.shared.submit(request)
} catch {
// Show error — can't run in background now
showError("Cannot export in background right now")
}
}
func handleExport(task: BGContinuedProcessingTask) {
var shouldContinue = true
task.expirationHandler = {
shouldContinue = false
}
// MANDATORY: Report progress
// Tasks with no progress updates are AUTO-EXPIRED
task.progress.totalUnitCount = Int64(photos.count)
task.progress.completedUnitCount = 0
Task {
for (index, photo) in photos.enumerated() {
guard shouldContinue else { break }
await exportPhoto(photo)
// Update progress — system displays to user
task.progress.completedUnitCount = Int64(index + 1)
}
task.setTaskCompleted(success: shouldContinue)
}
}
| Property | Type | Description |
|---|---|---|
identifier | String | With wildcard, can have dynamic suffix |
title | String | Shown in system progress UI |
subtitle | String | Shown in system progress UI |
strategy | Strategy | .fail or .enqueue (default) |
// .fail — Reject if can't start immediately
request.strategy = .fail
// .enqueue — Queue if can't start (default)
// Task may run later
// Check if GPU available for background task
let supportedResources = BGTaskScheduler.shared.supportedResources
if supportedResources.contains(.gpu) {
// GPU is available
}
Finish critical work (~30 seconds) when app transitions to background. For state saving, completing uploads.
var backgroundTaskID: UIBackgroundTaskIdentifier = .invalid
func applicationDidEnterBackground(_ application: UIApplication) {
backgroundTaskID = application.beginBackgroundTask(withName: "Save State") {
// Expiration handler — clean up immediately
self.saveProgress()
application.endBackgroundTask(self.backgroundTaskID)
self.backgroundTaskID = .invalid
}
// Do critical work
saveEssentialState { [weak self] in
guard let self = self,
self.backgroundTaskID != .invalid else { return }
// End task AS SOON AS work completes
UIApplication.shared.endBackgroundTask(self.backgroundTaskID)
self.backgroundTaskID = .invalid
}
}
endBackgroundTask immediately when done — don't wait for expiration.onChange(of: scenePhase) { newPhase in
if newPhase == .background {
startBackgroundTask()
}
}
Large downloads/uploads that continue even after app termination. Work handed off to system daemon.
lazy var backgroundSession: URLSession = {
let config = URLSessionConfiguration.background(
withIdentifier: "com.yourapp.downloads"
)
// App relaunched when task completes
config.sessionSendsLaunchEvents = true
// System chooses optimal time (WiFi, charging)
config.isDiscretionary = true
// Timeout for requests (not the download itself)
config.timeoutIntervalForRequest = 60
return URLSession(configuration: config, delegate: self, delegateQueue: nil)
}()
func downloadFile(from url: URL) {
let task = backgroundSession.downloadTask(with: url)
task.resume()
// Work continues even if app terminates
}
var backgroundSessionCompletionHandler: (() -> Void)?
func application(
_ application: UIApplication,
handleEventsForBackgroundURLSession identifier: String,
completionHandler: @escaping () -> Void
) {
// Store — call after all events processed
backgroundSessionCompletionHandler = completionHandler
}
extension AppDelegate: URLSessionDelegate, URLSessionDownloadDelegate {
func urlSession(
_ session: URLSession,
downloadTask: URLSessionDownloadTask,
didFinishDownloadingTo location: URL
) {
// MUST move file immediately — temp location deleted after return
let destination = getDestinationURL(for: downloadTask)
try? FileManager.default.moveItem(at: location, to: destination)
}
func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
// All events processed — call stored completion handler
DispatchQueue.main.async {
self.backgroundSessionCompletionHandler?()
self.backgroundSessionCompletionHandler = nil
}
}
}
| Property | Default | Description |
|---|---|---|
sessionSendsLaunchEvents | false | Relaunch app on completion |
isDiscretionary | false | Wait for optimal conditions |
allowsCellularAccess | true | Allow cellular network |
allowsExpensiveNetworkAccess | true | Allow expensive networks |
allowsConstrainedNetworkAccess | true | Allow Low Data Mode |
Pause app in debugger, then execute:
// Trigger task launch
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.yourapp.refresh"]
// Trigger task expiration
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.yourapp.refresh"]
Filter Console.app:
subsystem:com.apple.backgroundtaskscheduler
Check what's scheduled:
BGTaskScheduler.shared.getPendingTaskRequests { requests in
for request in requests {
print("Pending: \(request.identifier)")
print(" Earliest: \(request.earliestBeginDate ?? Date())")
}
}
| Factor | How to Check | Impact |
|---|---|---|
| Critically Low Battery | Battery < ~20% | Discretionary work paused |
| Low Power Mode | ProcessInfo.isLowPowerModeEnabled | Limited activity |
| App Usage | User opens app frequently? | Higher priority |
| App Switcher | Not swiped away? | Swiped = no background |
| Background App Refresh | backgroundRefreshStatus | Off = no BGAppRefresh |
| System Budgets | Many recent launches? | Budget depletes, refills daily |
| Rate Limiting | Requests too frequent? | System spaces launches |
// Low Power Mode
if ProcessInfo.processInfo.isLowPowerModeEnabled {
// Reduce background work
}
// Listen for changes
NotificationCenter.default.publisher(for: .NSProcessInfoPowerStateDidChange)
.sink { _ in
// Adapt behavior
}
// Background App Refresh status
switch UIApplication.shared.backgroundRefreshStatus {
case .available:
// Can schedule tasks
case .denied:
// User disabled — prompt in Settings
case .restricted:
// MDM or parental controls — cannot enable
@unknown default:
break
}
switch ProcessInfo.processInfo.thermalState {
case .nominal:
break // Normal operation
case .fair:
// Reduce intensive work
case .serious:
// Minimize all background activity
case .critical:
// Stop non-essential work immediately
@unknown default:
break
}
NotificationCenter.default.publisher(for: ProcessInfo.thermalStateDidChangeNotification)
.sink { _ in
// Respond to thermal changes
}
{
"aps": {
"content-available": 1
},
"custom-data": "your-payload"
}
apns-priority: 5 // Discretionary — energy efficient (recommended)
apns-priority: 10 // Immediate — only for time-sensitive
func application(
_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable: Any],
fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
guard userInfo["aps"] as? [String: Any] != nil else {
completionHandler(.noData)
return
}
Task {
do {
let hasNewData = try await fetchLatestData()
completionHandler(hasNewData ? .newData : .noData)
} catch {
completionHandler(.failed)
}
}
}
"Receiving 14 pushes in a window may result in only 7 launches, maintaining a ~15-minute interval."
Silent pushes are rate-limited. Don't expect launch on every push.
@main
struct MyApp: App {
@Environment(\.scenePhase) var scenePhase
var body: some Scene {
WindowGroup {
ContentView()
}
.onChange(of: scenePhase) { newPhase in
if newPhase == .background {
scheduleAppRefresh()
}
}
// App refresh handler
.backgroundTask(.appRefresh("com.yourapp.refresh")) {
scheduleAppRefresh() // Schedule next
await fetchLatestContent()
// Task completes when closure returns (no setTaskCompleted needed)
}
// Background URLSession handler
.backgroundTask(.urlSession("com.yourapp.downloads")) {
await processDownloadedFiles()
}
}
}
.backgroundTask(.appRefresh("com.yourapp.refresh")) {
await withTaskCancellationHandler {
// Normal work
try await fetchData()
} onCancel: {
// Called when task expires
// Keep lightweight — runs synchronously
}
}
.backgroundTask(.urlSession("com.yourapp.weather")) {
// Called when background URLSession completes
// Handle completed downloads
}
| Type | Runtime | API | Use Case |
|---|---|---|---|
| BGAppRefreshTask | ~30s | submit(BGAppRefreshTaskRequest) | Fresh content |
| BGProcessingTask | Minutes | submit(BGProcessingTaskRequest) | Maintenance |
| BGContinuedProcessingTask | Extended | submit(BGContinuedProcessingTaskRequest) | User-initiated |
| beginBackgroundTask | ~30s | beginBackgroundTask(withName:) | State saving |
| Background URLSession | As needed | URLSessionConfiguration.background | Downloads |
| Silent Push | ~30s | didReceiveRemoteNotification | Server trigger |
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>your.identifiers.here</string>
</array>
<key>UIBackgroundModes</key>
<array>
<string>fetch</string> <!-- BGAppRefreshTask -->
<string>processing</string> <!-- BGProcessingTask -->
</array>
// Launch
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"ID"]
// Expire
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"ID"]
WWDC: 2019-707, 2020-10063, 2022-10142, 2023-10170, 2025-227
Docs: /backgroundtasks, /backgroundtasks/bgtaskscheduler, /foundation/urlsessionconfiguration
Skills: axiom-background-processing, axiom-background-processing-diag
Last Updated: 2025-12-31 Platforms: iOS 13+, iOS 26+ (BGContinuedProcessingTask)
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.