Using Settings.bundle for iOS Environment Configuration

What is Settings.bundle?

Settings.bundle is a special resource bundle that integrates your app's settings into the iOS Settings app. It allows users (and developers) to configure app preferences without opening the app itself. This is particularly powerful during development for quickly switching between different API endpoints, adjusting timeout values, or toggling debug features.

Pro Tip

Settings.bundle is perfect for development and QA environments. You can include it in debug builds and exclude it from production builds to keep sensitive configuration options hidden from end users.

Creating Settings.bundle

Let's create a Settings.bundle for our iOS project step by step.

Step 1: Add Settings Bundle to Your Project

Open your Xcode project
Right-click on your project in the Project Navigator
Select New File...
Under iOS, choose Resource
Select Settings Bundle
Click Next and save it in your project root

Xcode will create a Settings.bundle folder containing a Root.plist file.

Step 2: Configure Root.plist

Open Root.plist and configure it with your desired settings. Here's a comprehensive example:

Root.plist (XML)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PreferenceSpecifiers</key>
    <array>
        
        <!-- Header Section -->
        <dict>
            <key>Type</key>
            <string>PSGroupSpecifier</string>
            <key>Title</key>
            <string>Environment Configuration</string>
            <key>FooterText</key>
            <string>Select the environment and configure API settings</string>
        </dict>
        
        <!-- Environment Selection -->
        <dict>
            <key>Type</key>
            <string>PSMultiValueSpecifier</string>
            <key>Title</key>
            <string>Environment</string>
            <key>Key</key>
            <string>environment</string>
            <key>DefaultValue</key>
            <string>development</string>
            <key>Values</key>
            <array>
                <string>development</string>
                <string>staging</string>
                <string>production</string>
            </array>
            <key>Titles</key>
            <array>
                <string>Development</string>
                <string>Staging</string>
                <string>Production</string>
            </array>
        </dict>
        
        <!-- Base URL -->
        <dict>
            <key>Type</key>
            <string>PSTextFieldSpecifier</string>
            <key>Title</key>
            <string>Base URL</string>
            <key>Key</key>
            <string>baseURL</string>
            <key>DefaultValue</key>
            <string>https://api-dev.example.com</string>
            <key>KeyboardType</key>
            <string>URL</string>
            <key>AutocapitalizationType</key>
            <string>None</string>
            <key>AutocorrectionType</key>
            <string>No</string>
        </dict>
        
        <!-- Network Settings Group -->
        <dict>
            <key>Type</key>
            <string>PSGroupSpecifier</string>
            <key>Title</key>
            <string>Network Settings</string>
        </dict>
        
        <!-- Session Timeout -->
        <dict>
            <key>Type</key>
            <string>PSTextFieldSpecifier</string>
            <key>Title</key>
            <string>Session Timeout</string>
            <key>Key</key>
            <string>sessionTimeout</string>
            <key>DefaultValue</key>
            <string>3600</string>
            <key>KeyboardType</key>
            <string>NumberPad</string>
        </dict>
        
        <!-- Request Timeout -->
        <dict>
            <key>Type</key>
            <string>PSTextFieldSpecifier</string>
            <key>Title</key>
            <string>Request Timeout</string>
            <key>Key</key>
            <string>requestTimeout</string>
            <key>DefaultValue</key>
            <string>30</string>
            <key>KeyboardType</key>
            <string>NumberPad</string>
        </dict>
        
        <!-- Debug Settings Group -->
        <dict>
            <key>Type</key>
            <string>PSGroupSpecifier</string>
            <key>Title</key>
            <string>Debug Options</string>
        </dict>
        
        <!-- Enable Logging -->
        <dict>
            <key>Type</key>
            <string>PSToggleSwitchSpecifier</string>
            <key>Title</key>
            <string>Enable Logging</string>
            <key>Key</key>
            <string>enableLogging</string>
            <key>DefaultValue</key>
            <true/>
        </dict>
        
        <!-- Mock API Responses -->
        <dict>
            <key>Type</key>
            <string>PSToggleSwitchSpecifier</string>
            <key>Title</key>
            <string>Mock API</string>
            <key>Key</key>
            <string>mockAPI</string>
            <key>DefaultValue</key>
            <false/>
        </dict>
        
        <!-- App Info Group -->
        <dict>
            <key>Type</key>
            <string>PSGroupSpecifier</string>
            <key>Title</key>
            <string>App Information</string>
        </dict>
        
        <!-- Version Display -->
        <dict>
            <key>Type</key>
            <string>PSTitleValueSpecifier</string>
            <key>Title</key>
            <string>Version</string>
            <key>Key</key>
            <string>appVersion</string>
            <key>DefaultValue</key>
            <string>1.0.0</string>
        </dict>
        
    </array>
</dict>
</plist>

Reading Settings in Swift

Now let's create a Swift class to read and manage these settings in your app.

AppConfiguration.swift

import Foundation

/// Manages app configuration from Settings.bundle
class AppConfiguration {
    
    // MARK: - Singleton
    static let shared = AppConfiguration()
    
    private let userDefaults = UserDefaults.standard
    
    // MARK: - Keys
    private enum SettingsKey: String {
        case environment
        case baseURL
        case sessionTimeout
        case requestTimeout
        case enableLogging
        case mockAPI
        case appVersion
    }
    
    // MARK: - Environment
    enum Environment: String {
        case development
        case staging
        case production
        
        var displayName: String {
            switch self {
            case .development: return "Development"
            case .staging: return "Staging"
            case .production: return "Production"
            }
        }
    }
    
    // MARK: - Properties
    
    /// Current environment
    var environment: Environment {
        let envString = userDefaults.string(forKey: SettingsKey.environment.rawValue) ?? "development"
        return Environment(rawValue: envString) ?? .development
    }
    
    /// Base API URL
    var baseURL: String {
        if let customURL = userDefaults.string(forKey: SettingsKey.baseURL.rawValue),
           !customURL.isEmpty {
            return customURL
        }
        
        // Fallback to environment-based URLs
        switch environment {
        case .development:
            return "https://api-dev.example.com"
        case .staging:
            return "https://api-staging.example.com"
        case .production:
            return "https://api.example.com"
        }
    }
    
    /// Session timeout in seconds
    var sessionTimeout: TimeInterval {
        let timeout = userDefaults.string(forKey: SettingsKey.sessionTimeout.rawValue) ?? "3600"
        return TimeInterval(timeout) ?? 3600
    }
    
    /// Request timeout in seconds
    var requestTimeout: TimeInterval {
        let timeout = userDefaults.string(forKey: SettingsKey.requestTimeout.rawValue) ?? "30"
        return TimeInterval(timeout) ?? 30
    }
    
    /// Enable debug logging
    var isLoggingEnabled: Bool {
        return userDefaults.bool(forKey: SettingsKey.enableLogging.rawValue)
    }
    
    /// Use mock API responses
    var isMockAPIEnabled: Bool {
        return userDefaults.bool(forKey: SettingsKey.mockAPI.rawValue)
    }
    
    // MARK: - Initialization
    
    private init() {
        registerDefaultSettings()
        updateAppVersion()
    }
    
    /// Register default values from Settings.bundle
    private func registerDefaultSettings() {
        let defaults: [String: Any] = [
            SettingsKey.environment.rawValue: "development",
            SettingsKey.baseURL.rawValue: "https://api-dev.example.com",
            SettingsKey.sessionTimeout.rawValue: "3600",
            SettingsKey.requestTimeout.rawValue: "30",
            SettingsKey.enableLogging.rawValue: true,
            SettingsKey.mockAPI.rawValue: false
        ]
        
        userDefaults.register(defaults: defaults)
    }
    
    /// Update app version in settings
    private func updateAppVersion() {
        if let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String,
           let build = Bundle.main.infoDictionary?["CFBundleVersion"] as? String {
            let versionString = "\(version) (\(build))"
            userDefaults.set(versionString, forKey: SettingsKey.appVersion.rawValue)
        }
    }
    
    // MARK: - Debug Helper
    
    /// Print current configuration (useful for debugging)
    func printConfiguration() {
        print("""
        
        ═══════════════════════════════════════
        📱 App Configuration
        ═══════════════════════════════════════
        Environment:      \(environment.displayName)
        Base URL:         \(baseURL)
        Session Timeout:  \(sessionTimeout)s
        Request Timeout:  \(requestTimeout)s
        Logging Enabled:  \(isLoggingEnabled)
        Mock API:         \(isMockAPIEnabled)
        ═══════════════════════════════════════
        
        """)
    }
}

Using Configuration in Your App

Here's how to use the configuration in different parts of your application.

Network Manager Integration

NetworkManager.swift

import Foundation

class NetworkManager {
    
    static let shared = NetworkManager()
    
    private var session: URLSession!
    private let config = AppConfiguration.shared
    
    private init() {
        setupSession()
    }
    
    private func setupSession() {
        let configuration = URLSessionConfiguration.default
        
        // Apply timeout from settings
        configuration.timeoutIntervalForRequest = config.requestTimeout
        configuration.timeoutIntervalForResource = config.sessionTimeout
        
        // Add custom headers based on environment
        var headers = configuration.httpAdditionalHeaders ?? [:]
        headers["X-Environment"] = config.environment.rawValue
        headers["Content-Type"] = "application/json"
        configuration.httpAdditionalHeaders = headers
        
        session = URLSession(configuration: configuration)
        
        // Log configuration if enabled
        if config.isLoggingEnabled {
            print("🌐 Network Manager initialized with:")
            print("   Base URL: \(config.baseURL)")
            print("   Request Timeout: \(config.requestTimeout)s")
            print("   Session Timeout: \(config.sessionTimeout)s")
        }
    }
    
    func request(
        endpoint: String,
        method: String = "GET",
        body: Data? = nil,
        completion: @escaping (Result) -> Void
    ) {
        // Check if mock API is enabled
        if config.isMockAPIEnabled {
            handleMockResponse(completion: completion)
            return
        }
        
        // Build URL from base URL and endpoint
        guard let url = URL(string: config.baseURL + endpoint) else {
            completion(.failure(NetworkError.invalidURL))
            return
        }
        
        var request = URLRequest(url: url)
        request.httpMethod = method
        request.httpBody = body
        
        // Log request if enabled
        if config.isLoggingEnabled {
            print("📤 \(method) \(url.absoluteString)")
        }
        
        let task = session.dataTask(with: request) { data, response, error in
            // Log response if enabled
            if self.config.isLoggingEnabled {
                if let httpResponse = response as? HTTPURLResponse {
                    print("📥 Response: \(httpResponse.statusCode)")
                }
            }
            
            if let error = error {
                completion(.failure(error))
                return
            }
            
            guard let data = data else {
                completion(.failure(NetworkError.noData))
                return
            }
            
            do {
                let decoded = try JSONDecoder().decode(T.self, from: data)
                completion(.success(decoded))
            } catch {
                completion(.failure(error))
            }
        }
        
        task.resume()
    }
    
    private func handleMockResponse(completion: @escaping (Result) -> Void) {
        if config.isLoggingEnabled {
            print("🎭 Using mock API response")
        }
        // Return mock data based on type
        // Implementation depends on your mock data strategy
    }
}

enum NetworkError: Error {
    case invalidURL
    case noData
}

Session Management

SessionManager.swift

import Foundation

class SessionManager {
    
    static let shared = SessionManager()
    
    private var sessionTimer: Timer?
    private let config = AppConfiguration.shared
    
    private init() {
        startSessionTimer()
    }
    
    func startSessionTimer() {
        // Invalidate existing timer
        sessionTimer?.invalidate()
        
        // Get timeout from configuration
        let timeout = config.sessionTimeout
        
        if config.isLoggingEnabled {
            print("⏱ Session timer started: \(timeout) seconds")
        }
        
        // Start new timer
        sessionTimer = Timer.scheduledTimer(
            withTimeInterval: timeout,
            repeats: false
        ) { [weak self] _ in
            self?.sessionExpired()
        }
    }
    
    func resetSessionTimer() {
        startSessionTimer()
    }
    
    private func sessionExpired() {
        if config.isLoggingEnabled {
            print("⏰ Session expired")
        }
        
        // Handle session expiration
        // Log out user, show login screen, etc.
        NotificationCenter.default.post(name: .sessionExpired, object: nil)
    }
    
    deinit {
        sessionTimer?.invalidate()
    }
}

extension Notification.Name {
    static let sessionExpired = Notification.Name("sessionExpired")
}

AppDelegate Integration

Initialize and log configuration when the app launches:

AppDelegate.swift

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        // Initialize configuration
        let config = AppConfiguration.shared
        
        // Print configuration in debug builds
        #if DEBUG
        config.printConfiguration()
        #endif
        
        // Setup based on environment
        setupEnvironment(config.environment)
        
        return true
    }
    
    private func setupEnvironment(_ environment: AppConfiguration.Environment) {
        switch environment {
        case .development:
            // Enable additional debugging tools
            print("🔧 Running in DEVELOPMENT mode")
            
        case .staging:
            // Staging-specific setup
            print("🧪 Running in STAGING mode")
            
        case .production:
            // Production-specific setup
            print("🚀 Running in PRODUCTION mode")
            // Disable debugging features
        }
    }
    
    func applicationDidBecomeActive(_ application: UIApplication) {
        // Reload configuration when app becomes active
        // This picks up any changes made in Settings app
        NotificationCenter.default.post(name: .settingsDidChange, object: nil)
    }
}

extension Notification.Name {
    static let settingsDidChange = Notification.Name("settingsDidChange")
}

Advanced Tips & Best Practices

1. Conditional Compilation

Include Settings.bundle only in debug builds:

Build Phase Script

#!/bin/bash

# Remove Settings.bundle from Release builds
if [ "${CONFIGURATION}" = "Release" ]; then
    echo "Removing Settings.bundle from Release build"
    rm -rf "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Settings.bundle"
fi

2. Observe Settings Changes

Listen for changes when app returns from background:

Swift

// In your ViewController or appropriate class
override func viewDidLoad() {
    super.viewDidLoad()
    
    NotificationCenter.default.addObserver(
        self,
        selector: #selector(settingsChanged),
        name: .settingsDidChange,
        object: nil
    )
}

@objc private func settingsChanged() {
    let config = AppConfiguration.shared
    
    // Reload your configuration
    if config.isLoggingEnabled {
        print("⚙️ Settings changed - reloading configuration")
        config.printConfiguration()
    }
    
    // Update UI or restart network services if needed
    updateUIBasedOnSettings()
}

deinit {
    NotificationCenter.default.removeObserver(self)
}

3. Environment-Specific App Icons

Add different app icons for each environment to easily identify which version you're running:

Visual Environment Indicators

Use different colored badges or overlays on your app icon (Dev = Green, Staging = Yellow, Prod = Red) to instantly know which environment you're using.

Testing Your Configuration

Here's a simple view controller to test your settings:

SettingsTestViewController.swift

import UIKit

class SettingsTestViewController: UIViewController {
    
    private let config = AppConfiguration.shared
    
    private lazy var stackView: UIStackView = {
        let stack = UIStackView()
        stack.axis = .vertical
        stack.spacing = 16
        stack.translatesAutoresizingMaskIntoConstraints = false
        return stack
    }()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        title = "Configuration Test"
        view.backgroundColor = .systemBackground
        
        setupUI()
        displayConfiguration()
    }
    
    private func setupUI() {
        view.addSubview(stackView)
        
        NSLayoutConstraint.activate([
            stackView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 20),
            stackView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20),
            stackView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20)
        ])
        
        let refreshButton = UIButton(type: .system)
        refreshButton.setTitle("Open Settings", for: .normal)
        refreshButton.addTarget(self, action: #selector(openSettings), for: .touchUpInside)
        stackView.addArrangedSubview(refreshButton)
    }
    
    private func displayConfiguration() {
        // Clear existing labels
        stackView.arrangedSubviews.forEach { view in
            if view is UILabel {
                view.removeFromSuperview()
            }
        }
        
        // Add configuration labels
        addLabel("Environment: \(config.environment.displayName)")
        addLabel("Base URL: \(config.baseURL)")
        addLabel("Session Timeout: \(config.sessionTimeout)s")
        addLabel("Request Timeout: \(config.requestTimeout)s")
        addLabel("Logging: \(config.isLoggingEnabled ? "ON" : "OFF")")
        addLabel("Mock API: \(config.isMockAPIEnabled ? "ON" : "OFF")")
    }
    
    private func addLabel(_ text: String) {
        let label = UILabel()
        label.text = text
        label.font = .systemFont(ofSize: 16)
        label.numberOfLines = 0
        stackView.addArrangedSubview(label)
    }
    
    @objc private func openSettings() {
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    }
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        displayConfiguration()
    }
}

Conclusion

Settings.bundle is an invaluable tool for iOS developers, providing a clean and efficient way to manage app configuration without rebuilding. By implementing environment switching through Settings.bundle, you can:

Quickly switch between Development, Staging, and Production environments
Adjust network timeouts and session durations on the fly
Toggle debug features without code changes
Test different API endpoints without reinstalling
Improve QA efficiency with easy-to-change configurations

Security Reminder

Always remove Settings.bundle from production builds or use conditional compilation to prevent exposing sensitive configuration options to end users. Use build scripts to automatically strip it from release builds.

This approach has saved countless hours in development and testing, making environment management seamless and error-free. Implement it in your next iOS project and experience the productivity boost!