[Swift] 실시간 걸음 수 위젯 만들기

 

HealthKit으로 '실시간처럼 보이는' 걸음 수 위젯 만들기

iOS 위젯에서 걸음 수를 '실시간 처럼' 보여주는 것은 생각보다 간단하지 않다.
위젯은 항상 켜져 있는 뷰가 아니라, 시스템이 필요할 때마 깨워서 스냅샷을 그리는 구조이기 때문이다.

이번 글에서는 아래의 내용을 중점으로 정리하려고 한다.

① 위젯이 진짜 실시간이 될 수 없는 이유
② HealthKit + WidgetKit 구조 설계
③ HealthKit에서 걸음 수 수집/합산하기
④ 위젯 타임라인 구성하기(오늘 걸음 수 표시)
⑤ ObserverQuery + background delivery로 '실시간처럼 보이게' 만들기

 

---

 

위젯이 진짜 실시간이 될 수 없는 이유

- 위젯은 항상 실행되는 프로세스가 아님

- 화면에 보이는 동안에도, 내부적으로는 한 번 렌더링 한 후,
시스템이 다시 갱신을 허용할 때만 새로 그릴 수 있음

- WidgetKit은 reloadTimelines, reloadAllTimelines() 등을 통해 '갱신 요청'은 할 수 있지만,
언제 실제로 새로 그릴지는 시스템이 휴리스틱으로 결정함

 

---

 

아키텍처 설계: HealthKit + WidgetKit

1. 공용 HealthKit Manager (App + Extension에서 같이 사용)
    - 걸음 수 권한 요청
    - 오늘 걸음 수 합산
    - ObserverQuery 등록 및 background delivery

2. 메인 앱
    - 최초 권한 요청 화면
    - HealthKit Manager 초기화
    - HealthKit 변경 이벤트 수신 시 → WidgetKit 갱신 요청

3. Widget Extension
    - TimelineProvider 에서 오늘 걸음 수 조회
    - TimelineEntry 에 걸음 수 + 날짜/시간 담기
    - View 에 표시

// Shared (App + Widget에서 공용으로 쓸 수 있는 모듈)
final class HealthKitStepService {
    // 권한 요청
    func requestAuthorization() async throws { ... }

    // 오늘 걸음 수 합산
    func fetchTodayStepCount() async throws -> Double { ... }

    // ObserverQuery + background delivery 설정
    func startObservingStepChanges(callback: @escaping () -> Void) { ... }
}

// App
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    let healthService = HealthKitStepService()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        healthService.startObservingStepChanges {
            // HealthKit 데이터 변경 감지 시
            WidgetCenter.shared.reloadAllTimelines()
        }
        return true
    }
}

// Widget Extension
struct StepWidgetProvider: TimelineProvider {
    func getTimeline(
        in context: Context,
        completion: @escaping (Timeline<StepEntry>) -> Void
    ) {
        Task {
            let steps = try? await HealthKitStepService.shared.fetchTodayStepCount()
            let entry = StepEntry(date: Date(), steps: Int(steps ?? 0))
            let next = Calendar.current.date(byAdding: .minute, value: 15, to: Date())!

            completion(Timeline(entries: [entry], policy: .after(next)))
        }
    }
}

---

 

HealthKit에서 걸음 수 가져오기

▶ 권한 요청
(info.plist에 추가)
NSHealthShareUsageDescription
NSHealthUpdateUsageDescription

import HealthKit

final class HealthKitStepService {
    static let shared = HealthKitStepService()
    private let store = HKHealthStore()

    private init() {}

    private var stepType: HKQuantityType {
        HKObjectType.quantityType(forIdentifier: .stepCount)!
    }

    // MARK: - Authorization
    func requestAuthorization() async throws {
        guard HKHealthStore.isHealthDataAvailable() else { return }

        let readTypes: Set = [stepType]
        // 걸음 수는 일반적으로 write는 필요 없음(필요하면 추가)
        let shareTypes: Set<HKSampleType> = []

        try await store.requestAuthorization(
            toShare: shareTypes,
            read: readTypes
        )
    }
}

 

▶ '오늘' 걸음 수 합산 쿼리
Widget과 App 양쪽에서 공통으로 사용할 함수

extension HealthKitStepService {
    func fetchTodayStepCount() async throws -> Double {
        let calendar = Calendar.current
        let now = Date()
        let startOfDay = calendar.startOfDay(for: now)

        var components = DateComponents()
        components.day = 1
        components.second = -1
        let endOfDay = calendar.date(byAdding: components, to: startOfDay)!

        let predicate = HKQuery.predicateForSamples(
            withStart: startOfDay,
            end: endOfDay,
            options: .strictStartDate
        )

        let queryDescriptor = HKSampleQueryDescriptor(
            predicates: [
                .quantitySample(type: stepType, predicate: predicate)
            ],
            sortDescriptors: []
        )

        let samples = try await queryDescriptor.result(for: store) as! [HKQuantitySample]

        let total = samples.reduce(0.0) { partial, sample in
            partial + sample.quantity.doubleValue(for: HKUnit.count())
        }

        return total
    }
}

실제 앱에서는 HKStatisticsQuery를 사용해 합산하는 방식도 많이 사용함.
핵심은 오늘 자정~23:59:59까지 범위를 명확히 정의하는 것.

 

---

 

Widget 타임라인 기본 구현

- Entry 정의

import WidgetKit

struct StepEntry: TimelineEntry {
    let date: Date
    let steps: Int
}

- Provider 구현

struct StepProvider: TimelineProvider {
    func placeholder(in context: Context) -> StepEntry {
        StepEntry(date: Date(), steps: 0)
    }

    func getSnapshot(in context: Context, completion: @escaping (StepEntry) -> Void) {
        let entry = StepEntry(date: Date(), steps: 1234)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<StepEntry>) -> Void) {
        Task {
            let steps = (try? await HealthKitStepService.shared.fetchTodayStepCount()) ?? 0

            let entry = StepEntry(date: Date(), steps: Int(steps))
            let nextUpdate = Calendar.current.date(byAdding: .minute, value: 15, to: Date())!

            let timeline = Timeline(entries: [entry], policy: .after(nextUpdate))
            completion(timeline)
        }
    }
}

여기까지는 15분마다 한 번 정도 오늘 걸음 수를 표시하는 위젯이다.
이제부터 '실시간처럼 보이게' 만들기 위해 HealthKit의 Observer 기능을 붙일 예정이다.

---

 

ObserverQuery + Background Delivery로 '실시간처럼 보이게' 만들기

- HealthKit 변경 감지
걸음 수는 Health 앱/워치/기기에서 끊임없이 추가된다.
HealthKit은 이 변화를 감지할 수 있도록 ObserverQuery와 background delivery를 제공한다.

extension HealthKitStepService {
    func startObservingStepChanges(callback: @escaping () -> Void) {
        let query = HKObserverQuery(sampleType: stepType, predicate: nil) { [weak self] _, completionHandler, error in
            if let error {
                print("ObserverQuery Error: \(error)")
                completionHandler()
                return
            }

            // 여기서 anchor 기반 AnchoredObjectQuery를 같이 돌려도 됨
            callback()

            // 반드시 호출해야 background mode에서 다시 깨우기
            completionHandler()
        }

        store.execute(query)

        // Background delivery 설정
        store.enableBackgroundDelivery(for: stepType, frequency: .immediate) { success, error in
            if let error {
                print("Background delivery error: \(error)")
            } else {
                print("Background delivery enabled: \(success)")
            }
        }
    }
}

위와 같이 설정해두면,
워치/아이폰이 걸음 데이터를 HealthKit에 쌓을 때마다 앱이 백그라운드에서 깨우는 이벤트를 받을 수 있다.

 

---

 

위젯 갱신 요청 연결

Observer 콜백에서 WidgetKit 갱신 요청을 호출한다.

import WidgetKit

final class StepWidgetRefresher {
    static let shared = StepWidgetRefresher()

    func requestReload() {
        WidgetCenter.shared.reloadAllTimelines()
    }
}

앱 구동 시,

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    let healthService = HealthKitStepService()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        healthService.startObservingStepChanges {
            StepWidgetRefresher.shared.requestReload()
        }

        return true
    }
}

흐름은 아래와 같다.

1. 워치/폰에서 새로운 걸음 데이터가 HealthKit에 기록된다.
2. HealthKit → ObserverQuery 콜백 호출 (백그라운드 가능)
3. 콜백에서 WidgetCenter.shared.reloadAllTimelines() 호출
4. 시스템이 허용하는 시점에 위젯이 다시 그려짐
5. getTimeline 이 다시 실행되면서 fetchTodayStepCount()를 호출
6. 새로 합산된 걸음 수가 위젯에 반영

위젯이 1초 단위로 계속 바뀌지는 않지만,
데이터가 갱신될 때마다 꽤 빠르게 따라가는 형태로 만들 수 있다.

 

---

 

'실시간처럼' 보이게 하기 위한 튜닝 포인트

- 타임라인 정책 설계
getTimeline 의 policy 를 너무 길게 잡으면,
Observer 쪽에서 reload 요청을 해도 반영이 늦게 느껴질 수 있따.

일반적인 패턴은

• 기본 타임라인은 policy: .after(Date().addingTimeInterval(60*30)) 정도로 여유있게
• ObserverQuery 이벤트 발생 시에는 즉시 reload 요청에 의존

이렇게 하면,

• 사용자가 위젯을 거의 안보는 상황에서는 시스템이 알아서 덜 자주 갱신하고
• HealthKit 데이터가 자주 바뀔 때는 Observer를 통해 좀 더 자주 갱신 요청을 하게 된다.

- 위젯 크기(가로/세로)별 UI 설계
실시간처럼 보이게 하려면, 숫자가 바뀌는 느낌을 강화하는 것도 중요하다.

• small 위젯
  • '오늘 걸음 수' 1줄 + 큰 숫자
  • 최근 업데이트 시각(ex. 최근 2분 전) 작은 텍스트
• Medium/Large 위젯
  • 오늘 총 걸음 수
  • 시간대별 막대 그래프 (미니 차트)
  • '목표 대비%' 게이지

이렇게 하면, 사용자 입장에서는 숫자가 자주 바뀐다는 인식이 생기면서 실시간 처럼 보이게 된다.

 

- 권한/에러 상태 처리
HealthKit 기반 위젯은 아래와 같은 상태를 고려해야 한다.

• 권한 미부여(처음 설치 후)
• 오늘 데이터 없음
• 백그라운드 전달 비활성화(사용자가 끈 경우)
• 위치 미연동/아이폰만 들고 있음

각 상태에 대해 위젯에서

• Health 데이터 접근 권한이 없습니다.
• 아직 걸음 데이터가 없습니다

등의 문자열을 별도로 노출해주면 UX 개선이 될 것 같다.

 

---

 

끝으로,

HealthKit 기반의 걸음 수 위젯은 구조적으로 완전한 실시간 갱신이 불가능하지만,
ObserverQuery·background delivery·타임라인 정책을 적절히 조합하면
사용자 입장에서는 '실시간처럼 반응하는 위젯'을 충분히 구현할 수 있었다.

결국 핵심은,
- HealthKit의 변화를 빠르게 감지하고
- 가능한 한 즉시 WidgetKit 갱신을 요청하며
- 위젯 UI와 타임라인을 “실시간에 가깝게 보이도록” 설계하는 것

이번 글에서는 이러한 구조를 실제 코드 기반으로 하나씩 구현해보며
'실시간처럼 보이는 걸음 수 위젯'이 어떤 방식으로 완성되는지 흐름을 정리해보았다.
HealthKit과 WidgetKit의 특성을 이해하고 나면,
위젯을 단순한 표시용 요소가 아닌
기기 데이터와 자연스럽게 연동되는 하나의 UI 컴포넌트로 바라볼 수 있을 것이다.

기회가 된다면, 걸음 수 그래프, 목표 대비 UI, 다양한 위젯 크기 대응 등
UI∙데이터 표현 확장에 대한 내용도 별도로 정리해볼 생각이다.

 

---