Line	Topic
~11	Framework overview
~115	About the HealthKit framework (architecture)
~246	Setting up HealthKit (entitlements, Info.plist)
~357	Authorizing access to health data
~517	Protecting user privacy
~586	Saving data to HealthKit
~673	Reading data from HealthKit (queries)
~760	HKHealthStore API reference
~968	Creating a Mobility Health App (sample project)
~1025	Data types (type identifiers)
~1614	Samples (HKSample, quantity, category, correlations)
~1871	Queries (sample, anchored, statistics, observer)
~2146	Visualizing State of Mind in visionOS
~2203	Logging symptoms associated with a medication
~2278	Workouts and activity rings
~2449	HKError and error handling
~3152	Executing observer queries
~4778	Background delivery (HKUpdateFrequency)
~5974	HKObjectType and subclasses
~7264	HKSampleType reference

Setup checklist

Add HealthKit capability in Xcode (enable Clinical Health Records only if needed).
Add NSHealthShareUsageDescription and NSHealthUpdateUsageDescription to Info.plist.
Check HKHealthStore.isHealthDataAvailable() before any HealthKit calls.
Create a single HKHealthStore instance and retain it for the app's lifetime.
Request authorization with requestAuthorization(toShare:read:) before reading or writing.

Common workflows

Reading data

Create the appropriate HKSampleType or HKQuantityType.
Build a query descriptor (e.g., HKSampleQueryDescriptor, HKStatisticsQueryDescriptor).
Execute the query against HKHealthStore.
Handle results on a background queue; dispatch to main for UI updates.

Saving data

Create an HKQuantitySample, HKCategorySample, or HKCorrelation.
Use matching units for the data type (e.g., .count() for steps, .meter() for distance).
Call healthStore.save(_:withCompletion:).
Check authorizationStatus(for:) before saving to catch permission issues early.

Background delivery

Enable Background Modes in Xcode (Background fetch).
Call enableBackgroundDelivery(for:frequency:withCompletion:) for each data type.
Register an HKObserverQuery with an update handler.
When woken, call healthStore.execute(_:) to re-run the query.

Workouts

Create an HKWorkoutConfiguration with activity type and location.
Start a workout session on Apple Watch with HKWorkoutSession.
Use HKLiveWorkoutBuilder to collect real-time samples.
End the session and save the workout with endCollection(withEnd:completion:).

Key types

Type	Purpose
`HKHealthStore`	Central access point; authorization, queries, saving
`HKQuantitySample`	Numeric health data (steps, heart rate, weight)
`HKCategorySample`	Enumerated data (sleep analysis, menstrual flow)
`HKCorrelation`	Composite samples (food, blood pressure)
`HKWorkout`	Fitness activity with duration, energy, distance
`HKObserverQuery`	Long-running query for store changes
`HKAnchoredObjectQueryDescriptor`	Track additions/deletions since last anchor
`HKStatisticsQueryDescriptor`	Aggregate calculations (sum, avg, min, max)
`HKStatisticsCollectionQueryDescriptor`	Time-bucketed statistics for charts

Privacy and authorization

HealthKit uses fine-grained authorization per data type.
Apps cannot detect if read permission was denied; queries simply return no data.
Use authorizationStatus(for:) to check write permission before saving.
Guest User sessions on visionOS restrict mutations; handle errorNotPermissibleForGuestUserMode.
Never use HealthKit data for advertising or sell it to third parties.

Platform availability

iPhone/Apple Watch/visionOS: Full HealthKit store with sync.
iPadOS 17+: Has its own HealthKit store.
iPadOS 16 and earlier / macOS 13+: Framework available but isHealthDataAvailable() returns false.
Use earliestPermittedSampleDate() on Apple Watch to find oldest available data.

Error handling

Check for these common HKError.Code values:

errorHealthDataUnavailable – Device doesn't support HealthKit.
errorHealthDataRestricted – Enterprise or parental restrictions.
errorAuthorizationNotDetermined – Authorization not yet requested.
errorAuthorizationDenied – User denied write permission.
errorNotPermissibleForGuestUserMode – Vision Pro guest session restriction.
errorRequiredAuthorizationDenied – Required clinical record types denied.

SwiftUI integration

Use the HealthKitUI framework for SwiftUI authorization:

import HealthKitUI

.healthDataAccessRequest(
    store: healthStore,
    shareTypes: allTypes,
    readTypes: allTypes,
    trigger: trigger
) { result in
    // Handle authorization result
}

Reminders

HealthKit store is thread-safe; samples are immutable.
Avoid samples longer than 24 hours; many types have duration limits.
Correlations store contained samples internally—don't save them separately.
Use HKDeletedObject via anchored queries to detect deletions.
For workout heart rate zones, use HKWorkoutActivity and route samples.

swift-health-kit

HealthKit

What to open

Document structure