HealthKit

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

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 HKWorkoutSession and HKLiveWorkoutBuilder, 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 NSHealthShareUsageDescription or NSHealthUpdateUsageDescription, causing immediate crash on launch.
• Creating multiple HKHealthStore instances 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 HKQuantityType dimension
• 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)

References

• HealthKit extended query patterns and workout builders
• HealthKit documentation
• HKHealthStore
• HKQuantityType
• HKWorkoutSession