What's new in BackgroundTasks — iOS & macOS 27 SDK

New

func

`submitTaskRequest`

NewiOStvOSwatchOS

open func submitTaskRequest(_ taskRequest: BGTaskRequest, completionHandler: @escaping @Sendable ((any Error)?) -> Void)

Submits a background task request to be scheduled with a completion handler.

This method asynchronously submits the task request and invokes the completion handler with any errors that occur during submission.

Submitting a task request for an unexecuted task that's already in the queue replaces the previous task request.

There can be a total of 1 refresh task and 10 processing tasks scheduled at any time. Trying to schedule more tasks will result in an error with code BGTaskSchedulerErrorCodeTooManyPendingTaskRequests.

Common errors include:

BGTaskSchedulerErrorCodeNotPermitted: Task identifier not permitted or unsupported resources requested
BGTaskSchedulerErrorCodeTooManyPendingTaskRequests: Too many pending tasks of this type
BGTaskSchedulerErrorCodeUnavailable: Background refresh disabled or app not permitted
BGTaskSchedulerErrorCodeImmediateRunIneligible: Immediate run not eligible due to system conditions

The completion handler is called on an arbitrary queue.

Note: The completion handler may be invoked on a arbitrary queue after an arbitrary amount of delay. Do not call this method from the main thread or performance-critical contexts.

This method replaces the deprecated submitTaskRequest:error: method

Parameters

taskRequest: The task request object representing the parameters of the background task to be scheduled.
completionHandler: A block that is called when submission completes. The block receives an optional error parameter: - nil if the task was submitted successfully - An NSError if submission failed

func

`submitTaskRequest`

NewiOStvOSwatchOS

open func submitTaskRequest(_ taskRequest: BGTaskRequest) async throws

Submits a background task request to be scheduled with a completion handler.

This method asynchronously submits the task request and invokes the completion handler with any errors that occur during submission.

Submitting a task request for an unexecuted task that's already in the queue replaces the previous task request.

Common errors include:

BGTaskSchedulerErrorCodeNotPermitted: Task identifier not permitted or unsupported resources requested
BGTaskSchedulerErrorCodeTooManyPendingTaskRequests: Too many pending tasks of this type
BGTaskSchedulerErrorCodeUnavailable: Background refresh disabled or app not permitted
BGTaskSchedulerErrorCodeImmediateRunIneligible: Immediate run not eligible due to system conditions

The completion handler is called on an arbitrary queue.

Note: The completion handler may be invoked on a arbitrary queue after an arbitrary amount of delay. Do not call this method from the main thread or performance-critical contexts.

This method replaces the deprecated submitTaskRequest:error: method

Parameters

taskRequest: The task request object representing the parameters of the background task to be scheduled.
completionHandler: A block that is called when submission completes. The block receives an optional error parameter: - nil if the task was submitted successfully - An NSError if submission failed

struct

`BGContinuedProcessingTaskRequest.Resources`

NewwatchOS

public struct Resources : OptionSet, @unchecked Sendable

Declaration

public struct Resources : OptionSet, @unchecked Sendable {

    public init(rawValue: Int)

    /// Indicate to the scheduler that the workload will require background GPU utilization.
    ///
    /// Task submissions will be rejected if the submitting app does not have the correct entitlement. Background GPU
    /// execution is not supported on all devices. Additionally, if a device is experiencing heavy GPU contention
    /// backgrounded workloads are not guaranteed runtime.
    ///
    /// - Important: Applications must have the `com.apple.developer.background-tasks.continued-processing.gpu`  entitlement to submit a task request with this resource.
    public static var gpu: BGContinuedProcessingTaskRequest.Resources { get }
}

enum

`BGContinuedProcessingTaskRequest.SubmissionStrategy`

NewwatchOS

public enum SubmissionStrategy : Int, @unchecked Sendable

Declaration

public enum SubmissionStrategy : Int, @unchecked Sendable {

    /// Fail the submission if there is no room for the task request, or if the system is under substantial load and is
    /// unable immediately run the task.
    case fail = 0

    /// Add the request to the back of a queue if there is no room for the submitted task or if the system is under
    /// substantial load and is unable to immediately run the task. Queued ``BGContinuedProcessingTaskRequest``s will be
    /// cancelled when the user removes your app from the app switcher.
    case queue = 1
}

Deprecated

func

`submit`

DeprecatediOStvOSvisionOSwatchOS

open func submit(_ taskRequest: BGTaskRequest) throws

DeprecatedUse submitTaskRequest:completionHandler: instead to capture all error conditions

Submit a previously registered background task for execution.

Submitting a task request for an unexecuted task that's already in the queue replaces the previous task request.

There can be a total of 1 refresh task and 10 processing tasks scheduled at any time. Trying to schedule more tasks returns BGTaskSchedulerErrorCodeTooManyPendingTaskRequests.

Parameters

taskRequest: The task request object representing the parameters of the background task to be scheduled.
error: If an error occurs, upon return contains an error object that indicates why the request was rejected

ReturnsYES if the request was successfully submitted; NO if there was an error

No APIs match your filter.

← More in App Intents & System Integration