Class

HKWorkoutSession

A workout session that tracks the user’s workout on Apple Watch.

Overview

The session fine tunes Apple Watch’s sensors for the specified activity. All workout sessions generate higher-frequency heart rate samples; however, an outdoor cycling activity generates more accurate location data, while an indoor cycling activity does not.

Apple Watch runs one workout session at a time. If a second workout starts while your workout is running, your HKWorkoutSessionDelegate object receives an HKError.Code.errorAnotherWorkoutSessionStarted error, and your session ends.

Running in the Background

Workout sessions also allow your app to continue running in the background. Background execution grants an app the following abilities:

  • The app continues to run throughout the entire workout session, even when the user lowers their wrist or interacts with a different app. When the user raises their wrist, the app reappears, letting the user quickly and easily check their current progress and performance.

  • The app can continue to access data from Apple Watch’s sensors in the background, letting you keep the app up to date at all times. For example, a running app can continue to track the user’s heart rate, ensuring that the most recent heart rate data is displayed whenever the user raises their wrist.

  • The app can alert the user using audio or haptic feedback while running in the background.

To maintain high performance on Apple Watch, you must limit the amount of work your app performs in the background. If your app uses an excessive amount of CPU while in the background, watchOS will suspend it. Use Xcode’s CPU report tool or the time profiler in Instruments to test your app’s CPU usage. The system also generates a log with a backtrace whenever your app crosses the CPU threshold and is terminated.

To run in the background, you must add the WKBackgroundModes key to your WatchKit extension’s Info.plist file. This key’s value is an array containing the workout-processing value. For more information, see WKBackgroundModes in Information Property List Key Reference.

To play audio or provide haptic feedback from the background, you must also add the UIBackgroundModes key to your WatchKit extension’s Info.plist file. This key’s value is an array containing the audio value.

Topics

Creating Workout Sessions

init(healthStore: HKHealthStore, configuration: HKWorkoutConfiguration)

Returns a newly instantiated workout session with an associated workout builder.

Beta

Monitoring the Session

var delegate: HKWorkoutSessionDelegate?

The workout session’s delegate.

protocol HKWorkoutSessionDelegate

The session delegate protocol defines an interface for receiving notifications about errors and changes in the workout session’s state.

Accessing the Workout Builder

func associatedWorkoutBuilder() -> HKLiveWorkoutBuilder

Returns the live workout builder associated with the workout session.

Beta

Managing the Workout

func prepare()

Prepares the workout session.

Beta
func pause()

Pauses the workout session.

Beta
func resume()

Resumes the workout session.

Beta
func end()

Ends the workout session.

Beta

Accessing Session Data

var endDate: Date?

The ending time and date for this workout session.

var startDate: Date?

The starting time and date for this workout session.

var state: HKWorkoutSessionState

The workout session’s current state.

var workoutConfiguration: HKWorkoutConfiguration

The configuration object that describes this workout.

Deprecated Methods

init(configuration: HKWorkoutConfiguration)

Returns a newly instantiated workout session.

Deprecated
var activityType: HKWorkoutActivityType

The workout activity performed during this session.

Deprecated
var locationType: HKWorkoutSessionLocationType

A value that indicates whether the workout session occurred indoors or outdoors.

Deprecated

Relationships

Inherits From

See Also

Sessions

Running Workout Sessions

Track the user’s activities on Apple Watch.

protocol HKWorkoutSessionDelegate

The session delegate protocol defines an interface for receiving notifications about errors and changes in the workout session’s state.

enum HKWorkoutSessionState

A workout session’s state.

class HKWorkoutConfiguration

An object that contains configuration information about a workout session.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software