Class

BGTaskScheduler

A class for registering launch handlers that are run by submitting task requests to launch your app in the background.

Declaration

class BGTaskScheduler : NSObject

Overview

A task is a standalone activity, such as cleaning a database, updating a machine learning model, or updating the displayed data for an app. To make efficient use of processing time and power, the system can launch your app in the background to run tasks like these when the device isn’t in use.

First you need to provide a launch handler, a block of code that performs a task. During app startup, register a launch handler and an associated unique identifier for each task. Submit a task request for the system to launch your app in the background at a later time to run the launch handler.

Running a task can happen many times and requires:

  • Configuring the app to enable background task execution.

  • Registering a launch handler for the task.

  • Scheduling the task.

A task object can specify an expiration handler and can inform the system when the associated task is complete.

Configure the App for Background Tasks

Configure the app for background tasks by adding the capabilities for the required background modes, and by adding a whitelist of task identifiers.

To add the capabilities:

  • Open the project editor and select the desired target.

  • Click Signing & Capabilities.

  • Expand the Background Modes section. If there’s no Background Modes, click the “+ Capability” button and choose Background Modes in the window that appears.

  • Select one or both of Background fetch and Background processing based on the needs of your background tasks.

The Xcode project editor showing the Background Modes capabilities editor of the Signing & Capabilities pane. A text callout points to the "+ Capability" button at the top-left above the editors and another callout identifies the two background mode checkbox items.

The system runs only tasks registered with identifiers on a whitelist of task identifiers. To add the whitelist, add the identifiers to the Info.plist file (The Info.plist File):

  • Open the Project navigator and select the desired target.

  • Click Info and expand Custom iOS Target Properties.

  • Add a new item to the list and choose “Permitted background task scheduler identifiers”, which corresponds to the BGTaskSchedulerPermittedIdentifiers array.

  • Add the string for each authorized task identifier as a separate item in the array.

The Xcode project editor showing the Custom iOS Target Properties editor of the Info pane. The example entries in the "Permitted background task schedule identifiers" array is identified by a text callout. There are two identifiers in the array and each one starts with the identifier for the developer, followed by a period and the app ID, and a period followed by an indication of what the task does. The first item is refresh, and the second is .db_cleaning.

Adding a BGTaskSchedulerPermittedIdentifiers key to the Info.plist disables application(_:performFetchWithCompletionHandler:) and setMinimumBackgroundFetchInterval(_:) on iOS 13 and later.

Register and Schedule Tasks

You must register all of the launch handlers before applicationDidFinishLaunching(_:) completes and there must be one launch handler for each identifier in the Info.plist.

Schedule a registered task at any time using submit(_:). Submitting a task again replaces the previous submission. Updating the settings of a scheduled task requires resubmitting the task.

Use Tasks in Extensions

Extensions can schedule tasks, such as the update of a machine learning model. Register tasks scheduled by extensions in the main app. The system launches the app to run the task.

Topics

Getting the Shared Task Scheduler

class var shared: BGTaskScheduler

The shared background task scheduler instance.

Scheduling a Task

func register(forTaskWithIdentifier: String, using: DispatchQueue?, launchHandler: (BGTask) -> Void) -> Bool

Register a launch handler for the task with the associated identifier that’s executed on the specified queue.

func submit(BGTaskRequest)

Submit a previously registered background task for execution.

Cancelling a Task

func cancel(taskRequestWithIdentifier: String)

Cancel a previously scheduled task request.

func cancelAllTaskRequests()

Cancel all scheduled task requests.

Getting All Scheduled Tasks

func getPendingTaskRequests(completionHandler: ([BGTaskRequest]) -> Void)

Request a list of unexecuted scheduled task requests.

Errors

class let errorDomain: String

The background tasks error domain as a string.

Structures

struct BGTaskScheduler.Error

The Errors for the BGTaskSchedulerError domain.

Relationships

Inherits From

Conforms To

See Also

Essentials

Starting and Terminating Tasks During Development

Use the debugger to start tasks and terminate them before completion during development.

Refreshing and Maintaining Your App Using Background Tasks

Use scheduled background tasks for refreshing your app content and for performing maintenance.