background-execution

Write and review Swift code that runs work while the app is backgrounded or suspended, choosing the right API for the job and respecting the system's constraints so the work actually runs and the app is not terminated.

Review process:

Establish the background execution model (lifecycle, budgets, force-quit, the five principles) using
```
references/fundamentals.md
```
.
Confirm the chosen API matches the work using the decision tree below; reroute if it does not.
Validate
```
BGTaskScheduler
```
usage (registration timing, Info.plist, expiration,
```
setTaskCompleted
```
) using
```
references/bg-task-scheduler.md
```
.

Validate task assertions (

beginBackgroundTask

endBackgroundTask

performExpiringActivity

) using

references/task-assertions.md

Validate background
```
URLSession
```
config and the relaunch flow using
```
references/background-url-session.md
```
.
Validate silent/VoIP push payloads, headers, and handlers using
```
references/background-push.md
```
.
Validate
```
UIBackgroundModes
```
declarations and location specifics using
```
references/background-modes.md
```
.
Validate background audio (session category, recording while locked, interruptions, route changes, mic permission) using
```
references/background-audio.md
```
.

Validate SwiftUI

ScenePhase

.backgroundTask

usage using

references/swiftui-background-tasks.md

Validate macOS schedulers (

NSBackgroundActivityScheduler

beginActivity

SMAppService

) using

references/macos-background.md

Check testing/debugging and constraint handling using
```
references/testing-and-debugging.md
```
.
Catch common mistakes using
```
references/anti-patterns.md
```
.

If doing partial work, load only the relevant reference files.

Task-based routing

Match the user's goal to the read order. Load only what you need.

"Refresh my app's content in the background"

references/bg-task-scheduler.md

BGAppRefreshTask

, register/submit/expiration

references/testing-and-debugging.md

- simulate the launch, handle

backgroundRefreshStatus

"Run long maintenance / ML / cleanup in the background"

references/bg-task-scheduler.md

BGProcessingTask

, power/network requirements

```
references/testing-and-debugging.md
```
- simulate launch and expiration

"Let a user-started export keep running after they leave (iOS 26)"

references/bg-task-scheduler.md

BGContinuedProcessingTask

, progress, submission strategy, GPU

```
references/fundamentals.md
```
- the consent / user-initiated principle

"Finish an in-flight upload / save when the app backgrounds"

references/task-assertions.md

beginBackgroundTask

endBackgroundTask

performExpiringActivity

"Download or upload a large file that survives suspension"

```
references/background-url-session.md
```
- background config, delegate, the relaunch flow
```
references/testing-and-debugging.md
```
- force-quit and constraint caveats

"Wake my app from the server"

```
references/background-push.md
```
- silent push payload/headers/handler, or PushKit for calls

references/background-modes.md

- the

remote-notification

mode

"Keep playing audio in the background"

```
references/background-audio.md
```
- the
```
audio
```
mode + active session, category/mode/options, interruptions, route changes

"Record / dictate / transcribe with the screen locked"

```
references/background-audio.md
```
-
```
.playAndRecord
```
, recording while locked, mic permission, AVAudioEngine taps, the production gotchas

"Track location in the background"

```
references/background-modes.md
```
- the
```
location
```
mode, significant-change and region monitoring

"Do this the SwiftUI way"

references/swiftui-background-tasks.md

ScenePhase

.backgroundTask(.appRefresh/.urlSession)

references/bg-task-scheduler.md

- you still schedule with

BGTaskScheduler

"Background work on macOS"

references/macos-background.md

NSBackgroundActivityScheduler

beginActivity

SMAppService

"My background task never runs / how do I test it"

```
references/testing-and-debugging.md
```
- lldb simulate commands, the states that gate execution
```
references/anti-patterns.md
```
- the usual causes

"I'm hitting bugs or App Review issues"

```
references/anti-patterns.md
```
- catches with before/after fixes

Decision tree

Which background API should I use?

Does the work require user consent or input mid-flight?
  -> Background runtime is wrong. Bring it to the foreground.

Is work already running and you just need to finish it as the app backgrounds?
  -> beginBackgroundTask / endBackgroundTask (apps)
  -> ProcessInfo.performExpiringActivity (app extensions, watchOS)

Is it a user-initiated long task that should continue with visible progress? (iOS/iPadOS 26)
  -> BGContinuedProcessingTask

Is it a large/long file download or upload that must survive suspension/termination?
  -> background URLSession

Does the server need to tell the app new content exists?
  -> background (silent) push  (apns-push-type: background, content-available: 1)

Is it an incoming call invitation?
  -> PushKit + CallKit (report the call on every push)

Is it periodic content refresh before the user opens the app?
  -> BGAppRefreshTask

Is it long, deferrable maintenance / ML / cleanup?
  -> BGProcessingTask (optionally requiresExternalPower / requiresNetworkConnectivity)

Does the app need to keep playing audio or recording the mic (incl. while locked)?
  -> audio UIBackgroundMode + active AVAudioSession (.playback or .playAndRecord)  [background-audio.md]

Does the app need to keep running for location / BLE / VoIP?
  -> declare the matching UIBackgroundModes capability  [background-modes.md]

macOS, deferrable repeating maintenance?
  -> NSBackgroundActivityScheduler

macOS, keep critical non-UI work from being napped?
  -> ProcessInfo.beginActivity / performActivity

Which BGTask type?

Short content refresh, system picks the time around app usage?
  -> BGAppRefreshTask          (UIBackgroundModes: fetch)

Long maintenance, ideally on charger + network?
  -> BGProcessingTask          (UIBackgroundModes: processing; requiresExternalPower / requiresNetworkConnectivity)

User-tapped long work with progress UI, continues after backgrounding? (iOS 26)
  -> BGContinuedProcessingTask (title/subtitle, progress, submission strategy, optional .gpu)

Long processing of health-research-study data? (iOS 17)
  -> BGHealthResearchTask

Core Instructions

Never treat background execution as guaranteed. It is opportunistic and discretionary; design every feature with a foreground reconciliation path and never put correctness-critical logic solely in a background task.
Never register a
```
BGTaskScheduler
```
handler lazily, in view code, or after launch finishes. Register all handlers in
```
App.init()
```
/
```
application(_:didFinishLaunchingWithOptions:)
```
, because the system may launch the app directly into the background. (
```
BGContinuedProcessingTask
```
is the one exception - it registers dynamically on user intent.)
Never register the same task identifier twice - it crashes the app.
Never omit the expiration handler on a
```
BGTask
```
; without one the system silently marks the task complete-and-unsuccessful. Set it, have it cancel work fast, and call
```
setTaskCompleted(success:)
```
exactly once.
Never forget to reschedule.
```
BGTaskScheduler
```
requests are one-shot; submit the next request as the first line of the launch handler.

Put

requiresExternalPower

requiresNetworkConnectivity

only on

BGProcessingTaskRequest

, never on app-refresh. Treat

earliestBeginDate

as a floor, not a schedule.

Never leave a
```
beginBackgroundTask
```
unbalanced. Call
```
endBackgroundTask
```
on both the success path and inside the expiration handler, idempotently (guard on
```
.invalid
```
); an unbalanced assertion kills the app. Call
```
beginBackgroundTask
```
before starting the work, not at the end of the background-transition delegate.
Never trust
```
backgroundTimeRemaining
```
as a real budget - it is
```
DBL_MAX
```
in the foreground and advisory in the background. Plan for ~30 s and rely on the expiration handler.
Use
```
beginBackgroundTask
```
(apps) or
```
performExpiringActivity
```
(extensions, watchOS) only to finish work already running, never to start fresh long work or schedule future work.
Never use completion-handler convenience methods or
```
dataTask
```
on a background
```
URLSession
```
; background sessions require a delegate. Create one session per identifier, store it, and recreate it at relaunch with the identical identifier and config.
Implement the full relaunch flow for background
```
URLSession
```
: store the handler from
```
handleEventsForBackgroundURLSession
```
, recreate the session, and call the stored handler from
```
urlSessionDidFinishEvents(forBackgroundURLSession:)
```
on the main thread. Move the file from
```
didFinishDownloadingTo
```
's
```
location
```
synchronously inside the callback.
For background uploads, use file-backed
```
uploadTask(with:fromFile:)
```
- data and stream uploads fail after the app exits.
Never send a silent push without
```
apns-push-type: background
```
(and
```
apns-priority: 5
```
), and keep the
```
aps
```
dictionary to
```
content-available
```
only. Call the fetch completion handler within ~30 s. Treat silent push as throttled and coalesced, not reliable.
On iOS 13+, report an incoming call to CallKit on every VoIP push, or the system terminates the app and revokes VoIP-push privileges. Never use VoIP pushes for non-call data.
Never set
```
allowsBackgroundLocationUpdates = true
```
without the
```
location
```
background mode - it is a fatal error. Prefer significant-change / region monitoring over the continuous
```
location
```
mode.
Background audio needs both the
```
audio
```
mode and an active
```
AVAudioSession
```
with a background-capable category (
```
.playback
```
for playback,
```
.playAndRecord
```
/
```
.record
```
for recording-while-locked); the mode alone does nothing. Activate the session when audio begins (not at launch) and deactivate with
```
.notifyOthersOnDeactivation
```
. Always handle
```
interruptionNotification
```
(check
```
.shouldResume
```
before resuming) and
```
routeChangeNotification
```
(pause on
```
.oldDeviceUnavailable
```
).
For mic capture, require permission with
```
AVAudioApplication.requestRecordPermission()
```
(iOS 17+) and declare
```
NSMicrophoneUsageDescription
```
- without the key the app crashes, and without permission capture returns silent zeroed samples, not an error. Install
```
AVAudioEngine
```
taps off the main actor (the closure runs on a realtime thread) and match
```
AVAudioFile
```
settings to the input node's format.
Declare
```
UIBackgroundModes
```
sparingly; App Review rejects unjustified modes. Prefer the lighter alternative.
Account for the user: a force-quit suppresses
```
BGTaskScheduler
```
, silent push, and background
```
URLSession
```
relaunch until the next manual launch. Read
```
backgroundRefreshStatus
```
(degrade on
```
.denied
```
, stay silent on
```
.restricted
```
) and back off under Low Power Mode and elevated thermal state.
Do background-relevant setup (task registration, session recreation, dependency wiring) on a path that runs on every launch, not in
```
.onAppear
```
/
```
.task
```
- a background launch may never build the UI.
With scenes enabled, use
```
sceneDidEnterBackground(_:)
```
(not the deprecated
```
applicationDidEnterBackground(_:)
```
); it has ~5 s to return.

On macOS use

NSBackgroundActivityScheduler

for deferrable maintenance and

ProcessInfo.beginActivity

endActivity

(balanced, or

performActivity

) to control App Nap;

performExpiringActivity

does not exist on macOS.

Test background tasks on a real device with the lldb
```
_simulateLaunchForTaskWithIdentifier:
```
/
```
_simulateExpirationForTaskWithIdentifier:
```
commands - never ship a reference to them. Always test the expiration path.

Output Format

If the user asks for a review, organize findings by file. For each issue:

State the file and relevant line(s).
Name the anti-pattern being replaced.
Show a brief before/after code fix.

Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.

If the user asks you to write or fix background-execution code, make the changes directly instead of returning a findings report.

Example output:

SyncManager.swift

Line 22:
BGTaskScheduler
handler registered in
.onAppear
- never runs on a background launch.

swift

// Before
.onAppear {
    BGTaskScheduler.shared.register(forTaskWithIdentifier: id, using: nil) { ... }
}

// After - register in App.init() / didFinishLaunching
init() {
    BGTaskScheduler.shared.register(forTaskWithIdentifier: id, using: nil) { task in
        self.handleRefresh(task: task as! BGAppRefreshTask)
    }
}

Line 48: missing expiration handler and
setTaskCompleted
- the app is killed at expiry.

swift

// Before
func handleRefresh(task: BGAppRefreshTask) { refresh() }

// After
func handleRefresh(task: BGAppRefreshTask) {
    scheduleNext()
    let op = RefreshOperation()
    task.expirationHandler = { op.cancel() }
    op.completionBlock = { task.setTaskCompleted(success: !op.isCancelled) }
    queue.addOperation(op)
}

Summary

Registration timing (high): move the handler to
```
App.init()
```
or it never fires on background launch.
Completion contract (high): add the expiration handler and call
```
setTaskCompleted
```
exactly once.

End of example.

References

```
references/fundamentals.md
```
- the execution model: foreground/background/suspended, system budgets, force-quit, user toggles, the five principles, the lifecycle and scene states, the "which API" map.

references/bg-task-scheduler.md

BackgroundTasks

BGAppRefreshTask

BGProcessingTask

BGContinuedProcessingTask

(iOS 26),

BGHealthResearchTask

, registration, Info.plist keys, submit, expiration, errors.

references/task-assertions.md

beginBackgroundTask

endBackgroundTask

backgroundTimeRemaining

ProcessInfo.performExpiringActivity

, assertions vs

BGTaskScheduler

references/background-url-session.md

- background

URLSession

config, mandatory delegate, the relaunch /

handleEventsForBackgroundURLSession

flow, knobs, resume data.

```
references/background-push.md
```
- silent/background push (payload, headers, handler, throttling), PushKit/VoIP + the CallKit requirement.
```
references/background-modes.md
```
- the
```
UIBackgroundModes
```
matrix, background location, BLE/accessory/PTT, deprecated background fetch.
```
references/background-audio.md
```
- background playback and recording:
```
AVAudioSession
```
categories/modes/options, recording while locked, mic permission, interruptions, route changes,
```
AVAudioEngine
```
taps and production gotchas.
```
references/swiftui-background-tasks.md
```
-
```
ScenePhase
```
, the
```
.backgroundTask
```
scene modifier, async cancellation, scheduling vs handling.

references/macos-background.md

NSBackgroundActivityScheduler

ProcessInfo.beginActivity

/App Nap,

SMAppService

, cross-platform map.

```
references/testing-and-debugging.md
```
- lldb simulate-launch/expiration,
```
backgroundRefreshStatus
```
, Low Power Mode, thermal state, what gates execution.
```
references/anti-patterns.md
```
- common mistakes LLMs make when generating background-execution code.