Set up and configure your HealthKit store.
Before using HealthKit, you must perform the following steps:
Enable HealthKit in your app.
Ensure that HealthKit is available on the current device.
Create your app’s HealthKit store.
Request permission to read and share data.
For a practical example of how to set up and use HealthKit, see SpeedySloth: Using HealthKit to build a workout app for Apple Watch.
Before you can use HealthKit, you must add the HealthKit capabilities for your app. In Xcode, select the project and turn on the HealthKit capability (see Figure 1). Only enable the Health Records checkbox if your app needs to access the user’s clinical records. App Review may reject apps that enable the Health Records capability if the app doesn’t use the Health Record data. For more information, see Accessing Health Records.
When you enable the HealthKit capabilities on an iOS app, Xcode adds HealthKit to the list of required device capabilities. This prevents users from purchasing or installing the app on devices that do not support HealthKit.
If HealthKit is not required for the correct operation of your app, you can open the app’s
Info file and delete the
healthkit entry from the
Required device capabilities array. The
healthkit entry is not used by WatchKit extensions.
Ensure HealthKit’s Availability
is method to confirm that HealthKit is available on the user's device.
Call this method before calling any other HealthKit methods. If HealthKit is not available on the device (for example, on an iPad), other HealthKit methods fail with an
error error. If HealthKit is restricted (for example, in an enterprise environment), the methods fail with an
Create the HealthKit Store
If HealthKit is both enabled and available, instantiate an
HKHealth object for your app as shown:
You need only a single HealthKit store per app. These are long-lived objects; you create the store once, and keep a reference for later use.
Request Permission to Read and Share Data
To help protect the user’s privacy, HealthKit requires fine-grained authorization. You must request permission to both read and share each data type used by your app before you attempt to access or save the data. However, you do not need to request permission for all data types at once. Instead, it may make more sense to wait until you need to access the data before asking for permission.
The example below shows the SpeedySloth app asking for permission to read and share energy burned, cycling distance, walking or running distance, and heart rate samples.
Any time your app requests new permissions, the system displays a form with all the requested data types shown. The user can toggle individual read and share permissions on and off, as in Figure 2. To learn how to provide a great user experience when asking for permissions, see HealthKit in iOS Human Interface Guidelines.
You must also provide custom messages for the permissions sheet. A separate custom message is required for both reading and writing HealthKit data. In your app’s I
nfo, set the NSHealthShareUsageDescription key to customize the message for reading data. Set the NSHealthUpdateUsageDescription key to customize the message for writing data.
If the user grants permission to share a data type, you can create new samples of that type and save them to the HealthKit store. However, before attempting to save any data, check to see if your app is authorized to share that data type by calling the
authorization method. If you have not yet requested permission, any attempts to save fail with an
HKError error. If the user has denied permission, attempts to save fail with an
To help protect the user’s privacy, your app does not know whether the user granted or denied permission to read data from HealthKit. If the user denied permission, attempts to query data from HealthKit return only samples that your app successfully saved to the HealthKit store.
Requesting permission to read and share data is only one part of protecting your user’s privacy. For more information, see Protecting User Privacy.
Specify Required Clinical Record Types
If your app requires access to specific clinical record data to function properly, specify the required clinical record types in your app’s
Info file using the
NSHealth key. This key defines the data types that your app must have permission to read. Set the value to an array of strings containing the type identifiers for your required types. For a list of type identifiers, see
To protect the user’s privacy, you must specify three or more required clinical record types. If the user denies authorization to any of the types, authorization fails with an
HKError error; your app is not told which record types the user denied access to.