HealthKit

What to open

Use
```
Articles/healtkit.md
```
for complete HealthKit documentation (188 pages consolidated).
Search within the file by section URLs or keywords like
```
HKHealthStore
```
,
```
HKQuantitySample
```
,
```
HKWorkout
```
,
```
HKObserverQuery
```
.

Document structure

The documentation file is organized by Apple documentation URLs as section headers. Key sections:

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:

swift

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

NPX Install

Tags

SKILL.md Content