Class

HKWorkout

A workout sample that stores information about a single physical activity.

Declaration

class HKWorkout : HKSample

Overview

The HKWorkout class is a concrete subclass of the HKSample class; however, they behave somewhat differently than other sample types.

  • You don’t need a specific type identifier to create the HKWorkoutType instance. All workouts use the same type identifier.

  • You must provide an HKWorkoutActivityType value for each workout. This value defines the type of activity performed during the workout.

  • After saving the workout to the HealthKit store, you must associate additional samples with the workout (for example, active energy burned or distance samples). These samples provide fine-grained details. Use the add(_:to:completion:) method to associate them with the workout.

An illustration showing how a workout is created and added to the store.

The workout records a summary of information about a single physical activity (for example, the duration, total distance, and total energy burned). It also acts as a container for other HKSample objects. You can associate any number of samples with a workout, adding details over the course of the workout. For example, you may want to break a single run into a number of shorter intervals, and then add samples to track the user’s heart rate, energy burned, distance traveled, and steps taken for each interval. For more information, see Adding Samples to a Workout.

HealthKit supports a wide range of activity types. For a complete list, see HKWorkoutActivityType.

Workouts are mostly immutable. You set their properties when you instantiate the workout, and they can’t change. However, you can continue to add samples to the workouts.

Fill the Activity Rings

Workouts can contribute to the Move and Exercise rings in the Activity app. To affect the rings, you must associate one or more active energy burned samples with the workout. Additionally:

  • In watchOS. Use a workout session to track the user’s activity. When the session has ended, create a workout object and the associated active energy burned samples. For more information, see HKWorkoutSession.

    The system updates the Move ring based on the active energy burned samples. It updates the Exercise ring based on the amount of time the user spent actually exerting themselves during the workout session, as calculated by the watch’s sensors.

  • In iOS. No additional work is necessary. Workout objects automatically contribute to both the Move and Exercise rings. The Exercise ring increases by the workout’s total duration, and the Move ring increases by the number of calories in the associated active energy burned samples. HealthKit also increases the Stand ring by one hour for each wall-clock hour that the workout overlaps.

Create and save workouts on the device that makes the most sense for your application—typically the device processing the user’s workout.

Extend Workouts

Like many HealthKit classes, the HKWorkout class should not be subclassed. You may extend workouts by adding metadata with custom keys as appropriate for your app.

For more information, see the methods init(activityType:start:end:duration:totalEnergyBurned:totalDistance:metadata:) and init(activityType:start:end:workoutEvents:totalEnergyBurned:totalDistance:metadata:).

Topics

Creating Workouts

Accessing Property Data

var duration: TimeInterval

The workout’s duration.

var totalDistance: HKQuantity?

The total distance traveled during the workout.

var totalEnergyBurned: HKQuantity?

The total active energy burned during the workout.

var workoutActivityType: HKWorkoutActivityType

The type of activity performed during the workout.

var workoutEvents: [HKWorkoutEvent]?

An array of workout event objects.

var totalFlightsClimbed: HKQuantity?

The total number of flights of stairs climbed during the workout.

var totalSwimmingStrokeCount: HKQuantity?

The total stroke count for the workout.

Specifying Sort Identifiers

let HKWorkoutSortIdentifierDuration: String

A constant for sorting workouts based on their duration.

let HKWorkoutSortIdentifierTotalDistance: String

A constant for sorting workouts based on their total distance.

let HKWorkoutSortIdentifierTotalEnergyBurned: String

A constant for sorting workouts based on the total energy burned.

Specifying Predicate Key Paths

let HKPredicateKeyPathWorkoutDuration: String

The key path for accessing the workout’s duration.

let HKPredicateKeyPathWorkoutTotalDistance: String

The key path for accessing the workout’s total distance.

let HKPredicateKeyPathWorkoutTotalEnergyBurned: String

The key path for accessing the workout’s total energy burned.

let HKPredicateKeyPathWorkoutType: String

The key path for accessing the workout’s type.

Specifying Metadata Keys

Workout Metadata Keys

Constants that can be used to add metadata to workouts.

Relationships

Inherits From

Conforms To

See Also

Samples

Adding Samples to a Workout

Create associated samples that add details to a workout.

class HKWorkoutBuilder

A builder object that incrementally constructs a workout.

class HKWorkoutType

A type that identifies samples that store information about a workout.

let HKWorkoutTypeIdentifier: String

The workout type identifier.

enum HKWorkoutActivityType

The type of activity performed during a workout.

class HKWorkoutEvent

An object representing an important event during a workout.