Contents

enableBackgroundDelivery(for:frequency:withCompletion:)

Enables the delivery of updates to an app running in the background.

Declaration

func enableBackgroundDelivery(for type: HKObjectType, frequency: HKUpdateFrequency, withCompletion completion: @escaping  @Sendable (Bool, (any Error)?) -> Void)
func enableBackgroundDelivery(for type: HKObjectType, frequency: HKUpdateFrequency) async throws

Parameters

  • type:

    The type of data to observe. This object can be a Hkcharacteristictype , Hkquantitytype, Hkcategorytype, or Hkworkouttype. Hkcorrelationtype is not a supported type for background delivery.

  • frequency:

    The maximum frequency of the updates. The system wakes your app from the background at most once per time period specified. For a complete list of valid frequencies, see Hkupdatefrequency.

  • completion:

    A block that this method calls as soon as it enables background delivery. It passes the following parameters:

    success

    A Boolean value. This parameter contains True if the system successfully enabled background delivery; otherwise, False.

    error

    An error object. If an error occurred, this object contains information about the error; otherwise, it is nil.

Mentioned in

Discussion

Call this method to register your app for background updates.

HealthKit wakes your app whenever a process saves or deletes samples of the specified type. The system wakes your app at most once per time period defined by the specified frequency. Some sample types have a maximum frequency of HKUpdateFrequency.hourly. The system enforces this frequency transparently.

For example, on iOS, stepCount samples have an hourly maximum frequency.

In watchOS, most data types have an hourly maximum frequency; however, the following data types can receive updates at HKUpdateFrequency.immediate:

Also, in watchOS, the background updates share a budget with WKApplicationRefreshBackgroundTask tasks. Your app can receive four updates (or background app refresh tasks) an hour, as long as it has a complication on the active watch face.

Receive Background Updates

As soon as your app launches, HealthKit calls the update handler for any observer queries that match the newly saved data. If you plan on supporting background delivery, set up all your observer queries in your app delegate’s application(_:didFinishLaunchingWithOptions:) method. By setting up the queries in application(_:didFinishLaunchingWithOptions:), you ensure that you’ve instantiated your queries, and they’re ready to use before HealthKit delivers the updates.

After your observer queries have finished processing the new data, you must call the update’s completion handler. This lets HealthKit know that your app successfully received the background delivery. If you don’t call the update’s completion handler, HealthKit continues to attempt to launch your app using a backoff algorithm to increase the delay between attempts. If your app fails to respond three times, HealthKit assumes your app can’t receive data and stops sending background updates.

For more information on the background delivery completion handler, see HKObserverQueryCompletionHandler.

See Also

Related Documentation

Managing background delivery