HealthKit API 완전 정복 — Workout 트래킹 관점에서 본 API 비교

extension HKQuantityTypeIdentifier {
    static let heartRate                  // 심박수 (count/min)
    static let distanceWalkingRunning     // 걷기/달리기 거리 (meter)
    static let distanceCycling            // 자전거 거리 (meter)
    static let distanceSwimming           // 수영 거리 (meter)
    static let activeEnergyBurned         // 활동 칼로리 (kcal)
    static let basalEnergyBurned          // 기초 대사 칼로리 (kcal)
    static let stepCount                  // 걸음 수 (count)
    static let flightsClimbed             // 오른 층수 (count)
    static let vo2Max                     // 최대산소섭취량 (ml/kg/min)
    static let runningPower               // 러닝 파워 (Watt, iOS 16+)
    static let runningSpeed               // 러닝 속도 (m/s, iOS 16+)
    static let runningStrideLength        // 보폭 (meter, iOS 16+)
    static let runningGroundContactTime   // 접지 시간 (ms, iOS 16+)
    static let runningVerticalOscillation // 수직 진동 (cm, iOS 16+)
}

HKUnit.count().unitDivided(by: .minute())
HKUnit.meter()
HKUnit.meterUnit(with: .kilo)
HKUnit.kilocalorie()
HKUnit.meter().unitDivided(by: .second())
HKUnit.minute().unitDivided(by: .meter().unitMultiplied(by: .kilo))

class HKQuantitySample: HKSample {
    let quantityType: HKQuantityType
    let quantity: HKQuantity
    let startDate: Date
    let endDate: Date
    let device: HKDevice?
    let sourceRevision: HKSourceRevision
    let metadata: [String: Any]?
}

let hrType = HKQuantityType.quantityType(forIdentifier: .heartRate)!
let bpmUnit = HKUnit.count().unitDivided(by: .minute())
let quantity = HKQuantity(unit: bpmUnit, doubleValue: 145.0)
 
let sample = HKQuantitySample(
    type: hrType,
    quantity: quantity,
    start: Date(),
    end: Date()
)

class HKWorkout: HKSample {
    let workoutActivityType: HKWorkoutActivityType
    let duration: TimeInterval
    let totalDistance: HKQuantity?          // (deprecated iOS 17+)
    let totalEnergyBurned: HKQuantity?      // (deprecated iOS 17+)
    let workoutEvents: [HKWorkoutEvent]?
    let workoutActivities: [HKWorkoutActivity]  // iOS 17+ 멀티스포츠
}

let config = HKWorkoutConfiguration()
config.activityType = .running
config.locationType = .outdoor
config.swimmingLocationType = .pool
config.lapLength = HKQuantity(unit: .meter(), doubleValue: 50)

let pauseEvent = HKWorkoutEvent(
    type: .pause,
    dateInterval: DateInterval(start: pausedAt, duration: 0),
    metadata: nil
)

enum HKAuthorizationStatus {
    case notDetermined
    case sharingDenied
    case sharingAuthorized
}

#if os(watchOS)
let session = try HKWorkoutSession(
    healthStore: store,
    configuration: config
)
session.delegate = self
session.startActivity(with: Date())
 
session.pause()
session.resume()
 
session.end()
#endif

class HKWorkoutSession {
    let healthStore: HKHealthStore
    let workoutConfiguration: HKWorkoutConfiguration
    let state: HKWorkoutSessionState
    weak var delegate: HKWorkoutSessionDelegate?
 
    func startMirroringToCompanionDevice(completion:)
}

#if os(watchOS)
let builder = session.associatedWorkoutBuilder()
builder.dataSource = HKLiveWorkoutDataSource(healthStore: store, workoutConfiguration: config)
builder.delegate = self
 
builder.beginCollection(withStart: Date()) { _, _ in }
 
let hrStats = builder.statistics(for: HKQuantityType.quantityType(forIdentifier: .heartRate)!)
let currentHR = hrStats?.mostRecentQuantity()?.doubleValue(for: bpmUnit)
 
builder.endCollection(withEnd: Date()) { _, _ in
    builder.finishWorkout { workout, error in
        // HKWorkout 저장 완료
    }
}
#endif

let builder = HKWorkoutBuilder(
    healthStore: store,
    configuration: config,
    device: .local()
)
 
builder.beginCollection(withStart: startDate) { success, error in }
 
let distanceSample = HKQuantitySample(
    type: HKQuantityType.quantityType(forIdentifier: .distanceWalkingRunning)!,
    quantity: HKQuantity(unit: .meter(), doubleValue: 1000),
    start: segmentStart,
    end: segmentEnd
)
builder.add([distanceSample]) { success, error in }
 
builder.addWorkoutEvents([pauseEvent]) { success, error in }
builder.addMetadata([HKMetadataKeyIndoorWorkout: false]) { success, error in }
 
builder.endCollection(withEnd: endDate) { success, error in
    builder.finishWorkout { workout, error in
        // HKWorkout 저장됨
    }
}

let routeBuilder = HKWorkoutRouteBuilder(healthStore: store, device: .local())
 
routeBuilder.insertRouteData([clLocation1, clLocation2]) { success, error in }
 
builder.finishWorkout { workout, error in
    guard let workout = workout else { return }
    routeBuilder.finishRoute(with: workout, metadata: nil) { route, error in
        // HKWorkoutRoute 저장 + workout과 연결
    }
}

let query = HKSampleQuery(
    sampleType: hrType,
    predicate: HKQuery.predicateForSamples(withStart: startDate, end: endDate),
    limit: HKObjectQueryNoLimit,
    sortDescriptors: [NSSortDescriptor(key: HKSampleSortIdentifierEndDate, ascending: false)]
) { _, samples, error in
    let hrSamples = samples as? [HKQuantitySample] ?? []
}
 
store.execute(query)

let query = HKAnchoredObjectQuery(
    type: hrType,
    predicate: HKQuery.predicateForSamples(withStart: sessionStart, end: nil),
    anchor: nil,
    limit: HKObjectQueryNoLimit
) { _, samples, deletedObjects, newAnchor, error in
    // 첫 호출: 기존 샘플 전부
}
 
query.updateHandler = { _, samples, deletedObjects, newAnchor, error in
    guard let newSamples = samples as? [HKQuantitySample] else { return }
    let latest = newSamples.max(by: { $0.endDate < $1.endDate })
}
 
store.execute(query)
 
store.stop(query)

let anchorData = try NSKeyedArchiver.archivedData(
    withRootObject: anchor,
    requiringSecureCoding: true
)
UserDefaults.standard.set(anchorData, forKey: "hr-anchor")
 
let data = UserDefaults.standard.data(forKey: "hr-anchor")!
let anchor = try NSKeyedUnarchiver.unarchivedObject(
    ofClass: HKQueryAnchor.self,
    from: data
)

let query = HKObserverQuery(
    sampleType: hrType,
    predicate: nil
) { _, completionHandler, error in
    completionHandler()
}
 
store.execute(query)
 
store.enableBackgroundDelivery(
    for: hrType,
    frequency: .immediate
) { success, error in }

let query = HKStatisticsQuery(
    quantityType: distanceType,
    quantitySamplePredicate: predicate,
    options: [.cumulativeSum]
) { _, statistics, error in
    let totalDistance = statistics?.sumQuantity()?.doubleValue(for: .meter())
}
 
store.execute(query)

let anchorDate = Calendar.current.startOfDay(for: Date())
let interval = DateComponents(hour: 1)
 
let query = HKStatisticsCollectionQuery(
    quantityType: hrType,
    quantitySamplePredicate: predicate,
    options: .discreteAverage,
    anchorDate: anchorDate,
    intervalComponents: interval
)
 
query.initialResultsHandler = { _, collection, error in
    collection?.enumerateStatistics(from: startDate, to: endDate) { stats, _ in
        let avgHR = stats.averageQuantity()?.doubleValue(for: bpmUnit)
    }
}
 
query.statisticsUpdateHandler = { _, _, collection, error in /* ... */ }
 
store.execute(query)

let typesToRead: Set<HKObjectType> = [
    HKQuantityType.quantityType(forIdentifier: .heartRate)!,
    HKQuantityType.quantityType(forIdentifier: .distanceWalkingRunning)!,
    HKObjectType.workoutType()
]
 
let typesToWrite: Set<HKSampleType> = [
    HKQuantityType.quantityType(forIdentifier: .distanceWalkingRunning)!,
    HKObjectType.workoutType()
]
 
store.requestAuthorization(toShare: typesToWrite, read: typesToRead) { success, error in
    // success는 "시트를 닫았는가"이지 "허용했는가"가 아니었다
}

let writeStatus = store.authorizationStatus(for: distanceType)
 
let readStatus = store.authorizationStatus(for: hrType)
// 실제로 거부됐어도 .sharingAuthorized로 보임

<key>NSHealthShareUsageDescription</key>
<string>운동 데이터 분석을 위해 필요합니다.</string>
 
<key>NSHealthUpdateUsageDescription</key>
<string>운동 기록을 건강 앱에 저장합니다.</string>

<key>com.apple.developer.healthkit</key>
<true/>
 
<key>com.apple.developer.healthkit.background-delivery</key>
<true/>

let query = HKSampleQuery(...) { _, samples, _ in
    if (samples ?? []).isEmpty {
        // 데이터가 없거나 권한 거부일 수 있음 → UI 안내
    }
}

quantity.doubleValue(for: .count())  // 잘못된 단위
quantity.doubleValue(for: HKUnit.count().unitDivided(by: .minute()))  // 올바른 단위

DispatchQueue.main.async {
    self.label.text = "\(bpm) bpm"
}