/background-processing

name: background-processing
description: Generates background processing infrastructure with BGTaskScheduler, background refresh, background downloads, and silent push handling. Use when user needs background tasks, periodic refresh, background URLSession downloads, or silent push notification processing.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Background Processing Generator

Generate production background processing infrastructure -- BGTaskScheduler for periodic refresh and long-running tasks, background URLSession for downloads/uploads that survive app termination, and silent push handling for server-triggered updates.

When This Skill Activates

Use this skill when the user:

• Asks to "add background processing" or "background tasks"
• Mentions "BGTaskScheduler" or "BGAppRefreshTask" or "BGProcessingTask"
• Wants "background refresh" or "periodic background updates"
• Asks about "background downloads" or "background uploads"
• Mentions "silent push" or "content-available push notifications"
• Wants data to sync or update while the app is in the background
• Asks about "background fetch" or "background execution"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (BGTaskScheduler requires iOS 13+)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check for @Observable support (iOS 17+ / macOS 14+)
• [ ] Identify source file locations

2. Existing Background Task Detection

Search for existing background task code:

Glob: **/*BackgroundTask*.swift, **/*BGTask*.swift, **/*BackgroundDownload*.swift
Grep: "BGTaskScheduler" or "BGAppRefreshTask" or "BGProcessingTask" or "backgroundSession"

If existing background code found:

• Ask if user wants to replace or augment it
• If augmenting, identify what is missing and generate only those pieces

3. Info.plist Check

Search for existing background modes configuration:

Grep: "BGTaskSchedulerPermittedIdentifiers" or "UIBackgroundModes"

Check for push notification entitlements if silent push is needed:

Glob: **/*.entitlements
Grep: "aps-environment"

Configuration Questions

Ask user via AskUserQuestion:

1. **What background processing do you need?**

• App refresh (lightweight periodic updates -- weather, feeds, content)
• Data processing (long-running -- database cleanup, ML model updates, large syncs)
• Background downloads (files, media, assets that survive app termination)
• Silent push notifications (server-triggered content updates)
• Multiple (select which combination)

2. **How often should background tasks run?**

• Hourly (system decides exact timing, best-effort)
• Every few hours (recommended for most apps)
• Daily (content that changes infrequently)
• On content change via push (server triggers update with silent push)

3. **Does the task need network access?**

• Yes -- needs background fetch or download capability
• No -- local processing only (database maintenance, cleanup)

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `BackgroundTaskManager.swift` -- Central manager for registering and scheduling all background tasks 2. `BackgroundTaskConfiguration.swift` -- Info.plist keys, entitlements, and task identifier constants

Step 3: Create Feature-Specific Files

Based on configuration: 3. `BackgroundDownloadManager.swift` -- If background downloads selected 4. `SilentPushHandler.swift` -- If silent push selected

Step 4: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/BackgroundProcessing/`
• If `App/` exists -> `App/BackgroundProcessing/`
• Otherwise -> `BackgroundProcessing/`

Output Format

After generation, provide:

Files Created

BackgroundProcessing/
├── BackgroundTaskManager.swift        # BGTaskScheduler registration & scheduling
├── BackgroundTaskConfiguration.swift  # Task identifiers and Info.plist config
├── BackgroundDownloadManager.swift    # Background URLSession downloads (optional)
└── SilentPushHandler.swift            # Silent push handling (optional)

Integration with App Lifecycle

**Register tasks at app launch (must happen before app finishes launching):**

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor private var appDelegate: AppDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        BackgroundTaskManager.shared.registerTasks()
        return true
    }
}

**Schedule refresh when app enters background:**

struct ContentView: View {
    @Environment(\.scenePhase) private var scenePhase

    var body: some View {
        NavigationStack {
            FeedView()
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                BackgroundTaskManager.shared.scheduleAppRefresh()
            }
        }
    }
}

**Start a background download:**

func downloadAsset(from url: URL) {
    BackgroundDownloadManager.shared.startDownload(from: url)
}

**Handle silent push in AppDelegate:**

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    await SilentPushHandler.shared.handle(userInfo: userInfo)
}

Testing

**Simulate background task in Xcode debugger (LLDB):**

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.app.refresh"]

**Simulate expiration:**

e -l objc -- (void)[[BGTaskSchedule