Article

Saving Data to HealthKit

Create and share HealthKit samples.

Overview

Your app can create new samples and add them to the HealthKit store. Although all sample types follow a similar procedure, each type has its own variations:

  1. Look up the type identifier for your data. For example, to record the user’s weight, you use the HKQuantityTypeIdentifierBodyMass type identifier. For the complete list of type identifiers, see Data Types.

  2. Use the convenience methods on the HKObjectType class to create the correct object type for your data. For example, to save the user’s weight, you’d create an HKQuantityType object using the quantityTypeForIdentifier: method. For a list of convenience methods, see HKObjectType.

  3. Instantiate an object of the matching HKSample subclass using the object type.

  4. Save the object to the HealthKit store using the saveObject:withCompletion: method.

Each HKSample subclass has its own convenience methods for instantiating sample objects, which modify the steps described in the list above.

An illustration showing how a quality sample relates to its identifier, type, and quantity.

For quantity samples, create an instance of the HKQuantity class. The quantity’s units must correspond to the allowable units described in the type identifier’s documentation. For example, the HKQuantityTypeIdentifierHeight documentation states that it uses length units. Therefore, your quantity must use centimeters, meters, feet, inches, or another compatible unit. For more information, see HKQuantitySample.

An illustration showing how a category sample relates to its identifier, type, and value.

For category samples, the sample’s value must correspond to the enum described in the type identifier’s documentation. For example, the HKCategoryTypeIdentifierSleepAnalysis documentation states that it uses the HKCategoryValueSleepAnalysis enum. Therefore, you must pass a value from this enum when creating this sample. For more information, see HKCategorySample.

An illustration showing how a correlation sample relates to its identifier, type, and contained objects.

For correlations, you must first create all the sample objects that the correlation will contain. The correlation’s type identifier describes both the type and the number of objects that can be contained. Do not save the contained objects into the HealthKit store. They are stored as part of the correlation. For more information, see HKCorrelation.

Balance Performance and Details

When saving data to the HealthKit store, you often need to choose between using a single sample to represent the data or splitting the data across multiple, smaller samples. A single, long sample is better from a performance perspective; however, multiple smaller samples gives the user a more detailed look into how their data changes over time. Ideally, you want to find a sample size that is granular enough to provide the user with useful historical data.

When recording a workout, you can use high frequency data (a minute or less per sample) to provide intensity charts and otherwise analyze the user’s performance over the workout. For less intensive activity, like daily step counts, samples of an hour or less often work best. This lets you produce meaningful daily and hourly graphs.

Apps should avoid saving samples that are 24 hours long or longer.

Work with Data in the Health App

The Health app gives users access to all of the data in their HealthKit store. Users can view, add, delete, and manage their data.

Specifically, users can:

  • See a dashboard containing their current health data.

  • Access all the data stored in HealthKit. Users can view the data by type, by app, or by device.

  • Manage each app’s permission to read and write from the HealthKit store.

As a result, the Health app has a few important impacts on developing HealthKit apps. First, remember that users can always modify their data outside your app or even change your permission to access their data. As a result, your app should always query for the current data in the HealthKit store or perform background queries to track changes to the store.

Second, you can also use the Health app to view the data your app is saving to the HealthKit store. This can be particularly useful during early testing, to verify that your app is saving everything as expected.

See Also

Health Data

Reading Data from HealthKit

Use queries to request sample data from HealthKit.

Data Types

Specify the kind of data used in HealthKit.

Samples

Create and save health and fitness samples.

Queries

Query health and fitness data.