iOS Background Capabilities Demo App

A comprehensive SwiftUI application that demonstrates various iOS background processing capabilities with SwiftData persistence for tracking and analyzing background task execution.

📱 Overview

This app provides practical, hands-on demonstrations of iOS background capabilities including:

Background App Refresh (BGAppRefreshTask)
Background Processing (BGProcessingTask)
Background URL Session Downloads
Background Audio Playback with continuous execution

All events are persisted using SwiftData, allowing you to track when tasks were scheduled, executed, and completed across app launches.

🎯 Key Features

1. Background App Refresh

Schedule periodic refresh tasks (15 min to 4 hours)
Simulates data fetching in the background
Shows scheduled vs actual execution times
Debug mode for immediate testing

2. Background Processing

Long-running background tasks (up to several minutes)
Different processing types: Database Cleanup, File Processing, Data Sync, ML Training
Progress tracking during execution
Demonstrates iOS preference for charging/WiFi conditions

3. Background Downloads

URLSession background configuration
Downloads continue even when app is terminated
Multiple concurrent downloads support
Sample URLs provided for testing
Progress tracking for active downloads

4. Background Audio

Plays generated 440Hz tone (A4 note)
Customizable duration (30 seconds to 10 minutes)
Continues playing when app is backgrounded
Lock screen and Control Center integration
Periodic logging every 30 seconds to verify background execution
Demonstrates that code continues running during background audio

🚀 Getting Started

Prerequisites

Xcode 15.0 or later
iOS 17.0 or later
Physical iOS device (recommended for testing background tasks)

Installation

Clone the repository
Open MyBackgroundTestApp.xcodeproj in Xcode
Select your development team in project settings
Build and run on a physical device (simulator has limitations for background tasks)

Required Capabilities

The app's Info.plist includes:

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
    <string>audio</string>
    <string>remote-notification</string>
</array>

📖 How to Use

Testing Background Fetch

Navigate to the App Refresh tab
Select an interval (15 minutes recommended for testing)
Tap "Schedule Refresh"
Lock your device and wait
Check history for execution times

Note: iOS determines actual execution time based on usage patterns, battery level, and other factors.

Testing Background Processing

Go to Processing tab
Choose a processing type
Tap "Schedule Task"
Plug in your device (iOS prefers to run these while charging)
Lock the screen and wait (best tested overnight)

Testing Background Downloads

Open Downloads tab
Select a sample download or enter custom URL
Tap to start download
Immediately minimize the app
Wait for completion notification
Downloads continue even if you force-quit the app!

Testing Background Audio

Switch to Audio tab
Select duration (5 minutes recommended)
Tap "Play"
Minimize the app
Audio continues playing
Check Control Center and Lock Screen for controls
Return to app to see periodic checkpoint logs (every 30 seconds)

📊 Event Tracking

All background events are stored with:

Event Type: Which background capability was used
Status: scheduled, running, completed, failed, cancelled, expired
Timestamp: When the event occurred
Duration: How long the task ran
Details: Descriptive information about the event

Events persist between app launches using SwiftData, providing a complete history of background activity.

⚙️ Configuration

Background Task Identifiers

App Refresh: com.app.refresh
Background Processing: com.app.processing

Adjustable Parameters

App Refresh intervals: 15 min, 30 min, 1 hour, 2 hours, 4 hours
Processing types with different durations
Audio playback duration: 30 seconds to 10 minutes
Download URLs can be customized

🔍 What to Look For

Success Indicators

✅ Events appear in history with "completed" status
✅ Timestamps show tasks ran while app was backgrounded
✅ Duration values indicate full execution
✅ Audio checkpoint logs show continuous background execution

Common Issues

❌ No background fetch events → Check Settings > General > Background App Refresh
❌ Processing tasks not running → Ensure device is charging
❌ Downloads failing → Check network connectivity
❌ No audio → Check device volume and mute switch

📱 System Requirements

Background Fetch

Runs more frequently for frequently-used apps
Requires Background App Refresh enabled in Settings
Typical interval: every few hours

Background Processing

Best when device is charging
Prefers WiFi connection
Can run for several minutes
Won't run if battery < 20%

Background Downloads

Managed by iOS for optimal battery/network usage
Continues through app termination
Automatically retries on failure

Background Audio

Requires audio session configuration
Keeps app running indefinitely while playing
Allows continuous code execution

🛠 Technical Details

Technologies Used

SwiftUI - User interface
SwiftData - Event persistence
BackgroundTasks - BGTaskScheduler framework
AVFoundation - Audio generation and playback
URLSession - Background downloads

Architecture

MVVM pattern with ObservableObject view models
SwiftData for persistence layer
Centralized background task management
Event-driven logging system

📝 Testing Checklist

Schedule app refresh and verify execution
Run background processing while charging
Start download and force-quit app
Play audio and minimize app
Check lock screen controls work
Verify events persist after app restart
Test interruption handling (calls, alarms)
Monitor battery impact in Settings
Export and analyze event logs

🤝 Contributing

This is a demonstration app for educational purposes. Feel free to fork and experiment with additional background capabilities!

📄 License

This project is available for educational use. Feel free to use it to learn about iOS background capabilities.

🙏 Acknowledgments

Created as a comprehensive demonstration of iOS background capabilities using modern SwiftUI and SwiftData technologies.

gestrich/background-processing-experiments