A session that gives your app additional time to run.
- watchOS 6.0+Beta
Normally, when the user lowers their wrist, the current app transitions to the background and becomes suspended. WatchKit provides background sessions that let apps continue running, even after the user stops interacting with them. For instance, workout sessions track the user’s motion and heart rate during a workout, background audio sessions play long-form audio, and continuous background location sessions track the user’s location.
Extended runtime sessions expand this opportunity to the following session types:
- Self care
Guide users through relatively brief activities. These activities focus on the user’s health or emotional well-being, such as tooth brushing.
Help users start and end silent meditation sessions. For walking meditation, consider using
HKWorkoutinstead. Similarly, if your app plays audio during the entire meditation session, there’s no reason to use a
WKExtended. The background audio mode already provides additional runtime as long as the audio is playing. For more information, see Playing Background Audio.
- Physical therapy
Guide users through stretching, strengthening, or range-of-motion exercises. If the physical therapy activity is strenuous—for example, riding an exercise bike—consider using an
- Smart alarm
Schedule a window of time to monitor the user’s heart rate and motion. The app uses this information to determine the optimal time to play an alarm, usually to wake the user from sleep.
Select a session type based on the app’s intended use—not based on the features that the session provides. Extended runtime sessions let the app continue to communicate with a bluetooth device, process data, or play sounds or haptics, even after the watch’s screen turns off.
Set Up the Session
Before starting an extended runtime session, enable your WatchKit extension’s Background Modes capability, and select your app’s session type (see Figure 1). Each app can only support one type of extended runtime session; however, it is possible to support other background modes in combination with extended runtime.
A physical therapy app, for example, might use a
WKExtended for range-of-motion exercises and an
HKWorkout for vigorous cross-training. Using separate sessions keeps the range-of-motion exercise from impacting the user’s Move and Exercise rings, but the user still gets full credit for the cross training.
To set up the session, instantiate a
WKExtended object, and assign your delegate. The system automatically creates a session based on the session type specified in your Background Modes capabilities.
WKExtended methods to track your session.
Finally, start your session. For most session types, you start the session immediately by calling
start(). For alarm sessions, you can schedule the session to start any time within the next 36 hours by calling
You must always start or schedule the extended runtime session when your app state is in the
Understand Session Behaviors
Extended runtime sessions gain the following features, based on the session type.
Frontmost sessions continue to run in the foreground. The watch screen does not need to remain on to keep your app alive. The session continues until the time limit expires, your app invalidates the session, or the user explicitly leaves your app (for example, by pressing the digital crown or switching to a different app).
Background sessions continue to run in the background, even if the user dismisses the app or launches another app. Background sessions continue to run until the time limit expires, or your app invalidates the session.
Finally, schedulable sessions can start any time within the next 36 hours. You must schedule the session in the
WKApplication state, but the system can then suspend or terminate your app without affecting the session. The system relaunches your app as needed to handle a scheduled session. You can only schedule one session at a time; if you need to reschedule a session, invalidate the current session, and schedule a new one.
After the session starts, the app continues to run in the background until the time limit expires, or your app invalidates the session. During the session, your app must trigger the alarm by calling the
play(_:) method. If your app is not active, playing the haptic displays a system alert to the user.
If you fail to play a haptic during the session, the system displays a warning and offers to disable future sessions.