Learn about the architecture and design of the HealthKit framework.
Framework
- Health
Kit
Overview
The HealthKit framework is designed to share data between apps in a meaningful way. The framework constrains the types of data and units to a predefined list, ensuring that all apps understand what the data means and how it can be used. Developers cannot create custom data types or units. Instead, HealthKit provides a wide variety of data types and units.
Additionally, the framework uses a large number of subclasses, producing deep hierarchies of similar classes. Often, these classes have subtle but important differences between them. For example, an HKQuantity
object is used to store data with a numeric value, while an HKCategory
object is used to store a value selected from an enumeration.
HealthKit also uses pairs of closely related classes. These classes must be paired correctly. For example, the HKObject
and HKObject
abstract classes have largely parallel hierarchies of concrete subclasses. When working with objects and object types, you must use matching subclasses.
HealthKit Data
HealthKit saves a variety of data types in the HealthKit Store:
Characteristic data. These records represent items that typically do not change, such as the user’s birthdate, blood type, biological sex, and skin type. You can read this data directly from the HealthKit store, using the
date
,Of Birth With Error: blood
,Type With Error: biological
, andSex With Error: fitzpatrick
methods. Your application cannot save characteristic data. The user must enter or modify this data using the Health app.Skin Type With Error: Sample data. Most of the user’s health data is stored in samples that represent data at a particular point in time. All sample classes are subclasses of the
HKSample
class, which is a subclass of theHKObject
class. These classes are described in more detail in Samples.Workout data. Information about fitness and exercise activities are stored as
HKWorkout
samples. WhileHKWorkout
is a subclass ofHKSample
, it behaves somewhat differently than other sample subclasses. These differences are described in Workout Data.Source data. Each sample stores information about its source. The
HKSource
object contains information about the app or device that saved the sample. TheRevision HKDevice
object contains information about the hardware device that generated the data.Deleted objects. An
HKDeleted
instance is used to temporarily store the UUID of an item that has been deleted from the HealthKit store. You can use deleted objects to respond when an object is deleted by the user or another app. For more information, seeObject HKAnchored
andObject Query HKDeleted
.Object
Properties of Objects and Samples
The HKObject
class is the superclass of all HealthKit sample types. All HKObject
subclasses are immutable. Each object has the following properties:
UUID. A unique identifier for that particular entry.
Metadata. A dictionary containing additional information about the entry. The metadata can contain both predefined and custom keys. The predefined keys facilitate the sharing of data between apps. Custom keys help extend a given HealthKit object type, adding app-specific data to the entry.
Source Revision. The source of the sample. The source can be a device that directly saves data into HealthKit, or an app. HealthKit automatically records each object’s source and version when the object is saved to the HealthKit store. This property is available only on objects retrieved from the store.
Device. The hardware device that generated the data stored in this sample.
The HKSample
class is a subclass of HKObject
. Sample objects represent data at a particular point in time, and all sample objects are subclasses of the HKSample
class. They have the following properties:
Type. The sample type, such as a sleep analysis sample, a height sample, or a step count sample.
Start date. The sample’s start time.
End date. The sample’s end time. If the sample represents a single point in time, the end time should equal the start time. If the sample represents data collected over a time interval, the end time should occur after the start time.
Samples are further divided into four concrete subclasses:
Category samples. Data that can be classified into a finite set of categories. See
HKCategory
.Sample Quantity samples. Data that can be stored as numeric values. Quantity samples are the most common data types in HealthKit. These include the user’s height and weight, as well as other data such as the number of steps taken, the user’s temperature, and their pulse rate. See
HKQuantity
.Sample Correlations. Composite data containing one or more samples. In iOS 8.0, HealthKit uses correlations to represent food and blood pressure. You should always use a correlation when creating food or blood pressure data. See
HKCorrelation
.Workouts. Data representing a physical activity, like running, swimming, or even play. Workouts often have type, duration, distance, and energy burned properties. You can also associate a workout with a number of fine-grained samples. Unlike correlations, these samples are not contained within the workout—however, they can be queried using the workout. For more information, see
HKWorkout
.
Threading
The HealthKit store is thread-safe, and most HealthKit objects are immutable. In general, you can use HealthKit safely in a multithreaded environment.
Note
All the HealthKit API’s completion handlers execute on private background queues. You will typically want to dispatch this data back to the main queue before updating your user interface or modifying any other resources that should be touched only by the main thread.
For more information about multithreading and concurrent programming, see Concurrency Programming Guide.
Syncing Data Between Devices
iPhone and Apple Watch each have their own HealthKit store, and data is automatically synced between the phone and watch. To save space, old data is periodically purged from Apple Watch. Use earliest
to determine the oldest samples available on Apple Watch.
HealthKit is not available on iPad.