Article

Preparing to Take Your watchOS App’s Snapshot

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

Overview

To provide a placeholder image for your app, watchOS periodically takes snapshots of your app’s user interface. Keeping your app's snapshot up to date helps produce apps that feel responsive and current. The system uses snapshots in two ways:

  • To represent your app in the dock.

  • As your app’s launch image.

The system displays the dock when the user presses the watch’s side button. The dock contains up to 10 apps. If the user lets the dock settle on an app for a moment, the system replaces the snapshot wit a running instance of the app. watchOS tries to keep these apps in memory so that they can resume quickly. These apps also receive priority for background tasks, helping you keep their content up to date. By default, the dock contains the 10 most-recently used apps; however, users can configure the dock to always contain certain apps.

When you launch an app, watchOS initially displays the latest snapshot for your app. As soon as the app is active, watchOS replaces the snapshot with the app’s live user interface.

Schedule Snapshots

The system automatically schedules snapshots for your app, for example when the app transitions from the foreground to the background, whenever the user interacts with the app’s complications or notifications, and one hour after the last user interaction. Your app can also invalidate its current snapshot and schedule a background snapshot refresh tasks by calling your extension’s scheduleSnapshotRefresh(withPreferredDate:userInfo:scheduledCompletion:) method. Additionally, you can request a new snapshot whenever another background task ends, by calling setTaskCompletedWithSnapshot(_:) and passing true.

The system budgets the number of snapshots you can take per hour. For apps in the dock, you can safely request one snapshot per hour. For apps with an active complication, you can request up to four per hour. If you exceed the available budget, the system may delay your request until additional background execution time becomes available.

Respond to Snapshot Background Tasks

To take a snapshot, the system resumes running your app in the background. It then calls your extension delegate’s handle(_:) method, passing a background snapshot request task. Use this task to update your user interface before the system takes a snapshot. You can push, pop, or present other interface controllers, and then update the content of the desired interface controller. The system automatically takes a snapshot of your user interface as soon as this task completes.

For more information, see WKSnapshotRefreshBackgroundTask.

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.

class WKRefreshBackgroundTask

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

class WKApplicationRefreshBackgroundTask

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

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.