A class you can use to update your app’s state in the background.


Do not subclass or create instances of this class yourself. Instead, schedule a background app refresh task by calling scheduleBackgroundRefresh(withPreferredDate:userInfo:scheduledCompletion:). When this background task is triggered, the system launches your app in the background, instantiates a WKApplicationRefreshBackgroundTask object, and passes the task object to your extension delegate’s handle(_:) method.

You often use a background app refresh task to drive other tasks. For example, if your server updates its data every day at 6:00, you might do the following:

  1. Call scheduleBackgroundRefresh(withPreferredDate:userInfo:scheduledCompletion:) to schedule a refresh just after 6:00.

  2. When the system triggers this task:

    1. Create a background URLSession task to download the updated data. For more information on background transfers, see URLSession.

    2. Call scheduleBackgroundRefresh(withPreferredDate:userInfo:scheduledCompletion:) to schedule the next update.

    3. Call setTaskCompletedWithSnapshot(_:) and pass false to end the background task without updating the snapshot.

  3. When the WKURLSessionRefreshBackgroundTask task is triggered, check the session to see if the information has downloaded successfully. If the download was successful:

    1. Update your user interface with the new data.

    2. Call setTaskCompletedWithSnapshot(_:) and pass true to end the background task and update the snapshot.

  4. When the WKSnapshotRefreshBackgroundTask task is triggered, because the user interface is already up to date, you can just call setTaskCompleted(restoredDefaultState:estimatedSnapshotExpiration:userInfo:). Pass [NSDate distantFuture] for the estimated snapshot expiration date, preventing the system from automatically scheduling another snapshot refresh.

Background app refresh tasks are budgeted. In general, the system performs approximately one task per hour for each app in the dock (including the most recently used app). This budget is shared among all apps on the dock. The system performs multiple tasks an hour for each app with a complication on the active watch face. This budget is shared among all complications on the watch face. After you exhaust the budget, the system delays your requests until more time becomes available.


Conforms To

See Also

Background Tasks

class WKRefreshBackgroundTask

The abstract superclass for WatchKit's other background task classes.

class WKURLSessionRefreshBackgroundTask

An object that helps you respond to URLSession background transfers.

class WKWatchConnectivityRefreshBackgroundTask

An object you use to receive background updates from the Watch Connectivity framework.

class WKSnapshotRefreshBackgroundTask

An object you use to update your app’s user interface in preparation for a snapshot.

class WKIntentDidRunRefreshBackgroundTask

An object you use to update your app after a SiriKit intent runs.

class WKRelevantShortcutRefreshBackgroundTask

An object you use to donate relevant Siri shortcuts.