A background task used to update your app’s state in the background.


class WKApplicationRefreshBackgroundTask : WKRefreshBackgroundTask


Do not subclass or create instances of this class. 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

Running watchOS Apps in the Background

Schedule and perform background tasks from within your app.

Playing Background Audio

Enable background audio in your app to provide a seamless playback experience.

Preparing to Take Your watchOS App’s Snapshot

Use snapshot background tasks to provide a timely, accurate snapshot of your app.

class WKRefreshBackgroundTask

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

class WKURLSessionRefreshBackgroundTask

A background task that helps you respond to URLSession background transfers.

class WKWatchConnectivityRefreshBackgroundTask

A background task used to receive background updates from the Watch Connectivity framework.

class WKSnapshotRefreshBackgroundTask

A background task used to update your app’s user interface in preparation for a snapshot.

class WKIntentDidRunRefreshBackgroundTask

A background task used to update your app after a SiriKit intent runs.

class WKRelevantShortcutRefreshBackgroundTask

A background task used to periodically donate relevant Siri shortcuts.

Background Session Keys

Enable background sessions.