A workout sample stores information about a single physical activity.
- iOS 8.0+
- Mac Catalyst 13.0+
- watchOS 2.0+
HKWorkout class is a concrete subclass of the
HKSample class. The workout records summary 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, letting you add fine-grain tracking 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.
HealthKit supports a wide range of activity types. For a complete list, see
Workouts are mostly immutable. You set their properties when you instantiate the workout, and they cannot change. However, you can continue to add samples to the workouts.
Adding Samples to a Workout
You can associate samples with a workout using the HealthKit store’s
add(_: method. The workout must be saved to the HealthKit store before you can add any samples. The samples don’t need to be saved. Adding them to the workout automatically saves them (if they have not been saved already). The following sample shows how to associate energy burned and heart rate samples with a workout.
You can create a query that returns only the samples associated with a workout by adding the workout to the query’s predicate. The
predicate method creates a predicate object that matches only samples associated with the provided workout.
Associating samples with a workout provides fine-grain information about the workout. However, adding samples to the workout does not change any of the workout’s properties. Specifically, adding distance samples won’t change the quantity stored in the
duration properties. Likewise, adding active energy burned samples won’t change the quantity stored in the
total property. This can lead to some duplication in data between the workout’s properties and the associated samples.
Your app should always provide data for the workout’s
total properties when the data is both available and relevant to the workout. In addition, you should provide a set of associated samples that sum up to these totals. You can also provide additional associated samples, to help track how the intensity of the exercise changed during the course of the workout.
For example, imagine an app that tracks a user’s runs. Whenever a user finishes a run, the app creates a workout that includes the total distance, duration, and calories burned for the entire run. The app also saves samples that describe the distance, calories burned, step count, heart rate, flights climbed, and other data over much smaller time intervals.
You need to fine tune the exact length of your associated samples based on the type of workout and the needs of your app. Using five-minute intervals minimizes the amount of memory needed to store the workouts, while still providing a general sense of the change in intensity over the course of a long workout. Using five-second intervals provides a much-more detailed view of the workout, but requires considerably more memory and processing.
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