BackgroundFetch¶

configure¶

func configure(minimumFetchInterval: TimeInterval = 0) async -> UIBackgroundRefreshStatus

Configure the plugin and begin listening for background-fetch events.

Calling configure automatically starts background-fetch (equivalent to calling BackgroundFetch.start immediately after configuration).

The BackgroundFetchConfig.minimumFetchInterval option controls how frequently iOS will wake your app in the background. Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports additional scheduling constraints such as requiredNetworkType, requiresCharging, etc.

Warning

You must call BackgroundFetch.finish within your event callback. Failure to do so will result in the OS throttling future background events for your app.

Basic configuration

let status = await BackgroundFetch.shared.configure(minimumFetchInterval: 15 * 60)  // seconds

BackgroundFetch.shared.onFetch(identifier: "MyApp") { event in
    if event.timeout {
        // The OS is about to suspend the app — finish immediately.
        print("[BackgroundFetch] TIMEOUT: \(event.taskId)")
        BackgroundFetch.shared.finish(taskId: event.taskId)
        return
    }
    print("[BackgroundFetch] Event received: \(event.taskId)")
    // Perform your work here...
    BackgroundFetch.shared.finish(taskId: event.taskId)
}

print("[BackgroundFetch] status: \(status)")

finish¶

func finish(taskId: String)

Signal to the OS that your background task is complete.

Warning

You must call finish at the end of every background-fetch event callback. Failure to call finish has serious consequences:

iOS — The OS may terminate your app and penalise future background-wake frequency.
Android — The JobScheduler job will not be considered complete and the OS may throttle or block future executions.

Always call finish as quickly as possible, even when your task encounters an error. For timeout events, call finish immediately without doing any additional work. Example

// Always finish — including on timeout. For timeout events, finish immediately.
BackgroundFetch.shared.onFetch(identifier: "MyApp") { event in
    if event.timeout {
        print("[BackgroundFetch] TIMEOUT: \(event.taskId)")
        BackgroundFetch.shared.finish(taskId: event.taskId)
        return
    }
    print("[BackgroundFetch] Event received: \(event.taskId)")
    defer { BackgroundFetch.shared.finish(taskId: event.taskId) }
    // Perform your work here...
}

scheduleTask¶

func scheduleTask(identifier: String, delay: TimeInterval, periodic: Bool = false, requiresExternalPower: Bool = false, requiresNetworkConnectivity: Bool = false, callback: @escaping (FetchEvent) -> Void) throws -> EventSubscription

Schedule a custom one-shot or periodic background task in addition to the default fetch event registered with BackgroundFetch.configure.

Custom tasks fire the same onEvent callback registered in BackgroundFetch.configure, identified by their TaskConfig.taskId. Call BackgroundFetch.finish with that taskId to signal completion, and BackgroundFetch.stop with the taskId to cancel.

iOS¶

On iOS, custom tasks are registered using the BGProcessingTask API. You must declare each taskId in your app's Info.plist under BGTaskSchedulerPermittedIdentifiers before calling scheduleTask.

Android¶

Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports all AbstractConfig scheduling constraints. One-shot task

// The task identifier must be listed in Info.plist BGTaskSchedulerPermittedIdentifiers.
try BackgroundFetch.shared.scheduleTask(
    identifier: "com.transistorsoft.customtask",
    delay: 5,          // seconds
    periodic: false
) { event in
    print("[BackgroundFetch] Event received: \(event.taskId)")
    // Perform your work here...
    BackgroundFetch.shared.finish(taskId: event.taskId)
}

start¶

func start(identifier: String? = nil) throws

Start subscribing to background-fetch events.

BackgroundFetch.configure calls start automatically. Use start explicitly only after a previous call to BackgroundFetch.stop. Example

// Resume after a previous stop().
try BackgroundFetch.shared.start()

status¶

var refreshStatus: UIBackgroundRefreshStatus { get async }

Query the current authorization status of the Background Fetch API.

Value	Constant	Description
`0`	BackgroundFetchStatus.STATUS_RESTRICTED	Background fetch updates are unavailable and the user cannot enable them again (e.g. parental controls).
`1`	BackgroundFetchStatus.STATUS_DENIED	The user explicitly disabled background behavior for this app or the whole system.
`2`	BackgroundFetchStatus.STATUS_AVAILABLE	Background fetch is available and enabled.
Example

// iOS returns the real UIBackgroundRefreshStatus.
let status = await BackgroundFetch.shared.refreshStatus
switch status {
case .available:  print("Background fetch available")
case .denied:     print("Background fetch denied by user")
case .restricted: print("Background fetch restricted")
@unknown default: break
}

stop¶

func stop(identifier: String? = nil)

Stop subscribing to background-fetch events.

If a taskId is provided, only that specific scheduled task is cancelled.
If no taskId is provided, all background-fetch and scheduled tasks are cancelled.

Use BackgroundFetch.start to resume after stopping. Example

// Stop all background-fetch scheduling.
BackgroundFetch.shared.stop()

// Stop a single scheduled task by identifier.
BackgroundFetch.shared.stop(identifier: "com.transistorsoft.customtask")