An object that manages behaviors that are shared among all of your app’s interface controllers.


class WKExtension : NSObject


Every WatchKit extension has a single extension object that is created and managed by the system. You use the extension object to perform app-level tasks such as opening URLs and getting the root interface controller of your app.

As relevant events occur within your WatchKit app, the extension object notifies its delegate of those events. Your delegate object can implement the methods it needs to provide an appropriate response to life cycle events, to handle notifications, or to handle Handoff–related behaviors. For more information about the methods of the delegate, see WKExtensionDelegate.

Frontmost App Behaviors

If your watchOS app is the frontmost app, the system displays it when the user raises their wrist.

An app becomes the frontmost app if it is running when the user drops their wrist. The app briefly transitions to the background and is suspended, as normal. However, if the user raises their wrist again while the app is still the frontmost app, the system automatically resumes and displays the app.

If the user dismisses the app in some other way (for example, by pressing the crown or by covering the screen), the app does not remain the frontmost app.

By default, an app remains the frontmost app for two minutes after the user drops their wrist. Users can configure this behavior using Settings > General > Wake Screen.

You can also request additional time as the frontmost app by setting the extension's isFrontmostTimeoutExtended property to true.

In watchOS 4, the frontmost app gains the following additional advantages:

  • Can play haptic feedback from the background.

  • Wakes from the background to receive notifications.

  • Wakes immediately upon the completion of a background transfer from a URLSession task or Watch Connectivity session.

  • Receives increased runtime priority when using the ProcessInfo object's performExpiringActivity(withReason:using:) method to complete tasks in the background.

For example, when the frontmost app receives a notification, rather than displaying the notification alert, it could play haptic feedback or a custom sound and then update its user interface.

Workout, location, and audio-recording apps appear to behave similarly to the frontmost app. However, these apps continue to run in the background throughout the entire workout, location, or recording session.

For more information, see HKWorkoutSession.

Receiving Background Data

When the system receives background data, it may not immediately wake the watchOS app to process that data. Instead, it may delay delivery of the data to preserve battery life.

When the system receives background data from either a URLSession task or a Watch Connectivity session:

  • All apps (watchOS 3 and earlier). There is no guarantee on when the system will wake the app to deliver the data. In some cases, the app may not receive the data until the user launches the app.

  • Frontmost apps (watchOS 4 and later). The system wakes the app immediately to deliver the data.

  • All other apps (watchOS 4 and later). The system wakes the app within 10 minutes to deliver the data.


Getting the Extension Object

class func shared() -> WKExtension

Returns the shared WatchKit extension object.

Accessing the Extension Delegate

var delegate: WKExtensionDelegate?

The delegate of the WatchKit extension object.

protocol WKExtensionDelegate

A collection of methods you can implement to manage the app-level behavior of your WatchKit extension.

Opening a URL Resource

func openSystemURL(URL)

Opens the specified system URL.

Getting the Interface Controllers

var rootInterfaceController: WKInterfaceController?

The app’s root interface controller.

var visibleInterfaceController: WKInterfaceController?

Returns the last visible interface controller.

Managing the Execution State

var applicationState: WKApplicationState

The runtime state of the Watch app.

enum WKApplicationState

The running states of your Watch app.

var isApplicationRunningInDock: Bool

A Boolean value that indicates whether the app is running in the dock.

var isFrontmostTimeoutExtended: Bool

A Boolean value that determines whether the app extends its time as the frontmost app.

Managing the User Interface

var isAutorotating: Bool

A Boolean value that determines whether the interface automatically rotates when the user flips their wrist.

var isAutorotated: Bool

A Boolean value that indicates whether the user interface is currently rotated so that it is properly oriented for another viewer.

func enableWaterLock()

Disables the Apple Watch touch screen to prevent accidental taps while the watch is submerged.


Inherits From

Conforms To

See Also

Extension Architecture

protocol WKExtensionDelegate

A collection of methods you can implement to manage the app-level behavior of your WatchKit extension.

class WKInterfaceDevice

An object that provides information about the user’s Apple Watch.