Create and share HealthKit samples.
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:
Use the convenience methods on the
HKObjectclass to create the correct object type for your data. For example, to save the user’s weight, you’d create an
HKQuantityobject using the
quantitymethod. For a list of convenience methods, see
Instantiate an object of the matching
HKSamplesubclass using the object type.
Save the object to the HealthKit store using the
HKSample subclass has its own convenience methods for instantiating sample objects, which modify the steps described in the list above.
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
height documentation states that it uses length units. Therefore, your quantity must use centimeters, meters, feet, inches, or another compatible unit. For more information, see
For category samples, the sample’s value must correspond to the enum described in the type identifier’s documentation. For example, the
sleep documentation states that it uses the
HKCategory enum. Therefore, you must pass a value from this enum when creating this sample. For more information, see
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
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.