Set up and configure your HealthKit store.
- Bundle Resources
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.
The first three steps are described in detail below. For more information on requesting authorization, see . For a practical example of how to set up and use HealthKit, see SpeedySloth: Creating a Workout.
Before you can use HealthKit, you must enable the HealthKit capabilities for your app. In Xcode, select the project and add the HealthKit capability (see Figure 1). Only select the Clinical Health Records checkbox if your app needs to access the user’s clinical records. App Review may reject apps that enable the Clinical Health Records capability if the app doesn’t actually 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, which prevents users from purchasing or installing the app on devices that don’t support HealthKit.
If HealthKit isn’t 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 isn’t 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 don’t 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. Xcode requires a separate custom message for 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.