Access, query, and store health and fitness metrics in Apple Health using HealthKit. Covers authorization, quantity samples, statistics collection queries, background delivery, and workout sessions. Targets Swift 6.3 / iOS 26+.
Contents
- Capabilities and Privacy
- Availability and HKHealthStore
- Query Selection Matrix
- Writing Samples and Units
- Route by Task
- Common Mistakes
- Review Checklist
- References
Capabilities and Privacy
Enable HealthKit in Signing & Capabilities. If your app observes updates in the background, enable the Background Delivery checkbox.
Declare usage descriptions in Info.plist:
NSHealthShareUsageDescription: Required for reading health data.NSHealthUpdateUsageDescription: Required for writing health data.NSHealthClinicalHealthRecordsShareUsageDescription: Required if accessing clinical records.
[!IMPORTANT] Request only the exact types needed for the immediate feature. App Review strictly rejects apps requesting unneeded health permissions.
Availability and HKHealthStore
Always guard initialization with HKHealthStore.isHealthDataAvailable(). HealthKit is supported on iPhone, Apple Watch, iPad (iPadOS 17+), and Vision Pro, but unavailable on iPadOS 16 or earlier and managed devices with restrictions.
guard HKHealthStore.isHealthDataAvailable() else { return }
let healthStore = HKHealthStore() // Single thread-safe shared store
Query Selection Matrix
| Query Type | Best Used For | Execution |
|---|---|---|
HKSampleQueryDescriptor |
Raw individual samples with sorting and limits | One-shot async |
HKStatisticsQueryDescriptor |
Single aggregate metric (sum, average, min/max) over a date range | One-shot async |
HKStatisticsCollectionQueryDescriptor |
Time-series aggregations (daily step charts, hourly heart rate) | One-shot or continuous |
HKAnchoredObjectQueryDescriptor |
Incremental synchronization with anchor tokens | One-shot or streaming |
HKObserverQuery |
Background delivery triggers when health data changes | Background notification |
Writing Samples and Units
Always specify compatible HKUnits matching the quantity type. For cumulative metrics (steps, active energy), set start and end dates encompassing the measurement interval; for discrete metrics (heart rate), use identical start and end dates.
Route by Task
- For statistics collection queries and SwiftUI health chart configurations, read Statistics and Charts.
- For background observation and setting up
enableBackgroundDelivery, read Background Delivery. - For recording live workouts with
HKWorkoutSessionandHKLiveWorkoutBuilder, read Live Workout Sessions. - For complete HKUnit string formats, conversion, and compound units, read HKUnit Reference.
Common Mistakes
- Calling HealthKit APIs without checking
HKHealthStore.isHealthDataAvailable(). - Missing
NSHealthShareUsageDescriptionorNSHealthUpdateUsageDescription, causing immediate crash on launch. - Creating multiple
HKHealthStoreinstances instead of sharing a single instance across the app. - Assuming read authorization can be inspected (Apple intentionally masks read authorization status for privacy).
- Using incompatible units (e.g. attempting to store step count with
.meter()instead of.count()).
Review Checklist
-
HKHealthStore.isHealthDataAvailable()checked before accessing store - Info.plist contains both share and update descriptions
- HealthKit capability enabled in target signing
- Read and write authorization requested in separate explicit sets
- Unit matches target
HKQuantityTypedimension - Background delivery enabled with
enableBackgroundDelivery(for:frequency:) - Queries use predicate intervals to prevent scanning full lifetime history
- UI gracefully handles devices where HealthKit is unavailable (e.g. iPadOS 16)