2nd/10_Wiki/Topics/Coding/iOS_watchOS_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
ios-watchos-patterns	watchOS — Watch app / 복잡도 제한 / 통신	Coding	draft	B	conceptual	2026-05-09	2026-05-09	ios watchos vibe-coding	language applicable_to Swift / SwiftUI / WatchConnectivity watchOS		watchOS Apple Watch complications WatchConnectivity WCSession

watchOS

단순 + 빠른. 30초 이상 화면 X. SwiftUI 표준. iPhone ↔ Watch 통신 = WatchConnectivity. Complications + smart stack 이 진짜 가치.

📖 핵심 개념

• App: short interaction (10-30초).
• Complication: 시계 face 의 작은 데이터.
• Smart Stack: 위젯처럼 timeline.
• Connectivity: iPhone 과 데이터 공유.

💻 코드 패턴

Watch app 구조

@main
struct WatchApp: App {
    var body: some Scene {
        WindowGroup {
            NavigationStack {
                HomeView()
            }
        }
    }
}

struct HomeView: View {
    @StateObject var vm = HomeViewModel()
    var body: some View {
        List(vm.items) { item in
            NavigationLink(value: item) {
                HStack { Image(systemName: "clock"); Text(item.name) }
            }
        }
        .navigationDestination(for: Item.self) { ItemDetail($0) }
    }
}

Complication (WidgetKit, watchOS 9+)

struct WatchComplication: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "step", provider: StepProvider()) { entry in
            Text("\(entry.steps)")
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .supportedFamilies([
            .accessoryCircular,
            .accessoryCorner,
            .accessoryInline,
            .accessoryRectangular,
        ])
    }
}

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

struct StepProvider: TimelineProvider {
    func placeholder(in context: Context) -> StepEntry { StepEntry(date: Date(), steps: 0) }
    func getSnapshot(in context: Context, completion: @escaping (StepEntry) -> Void) { ... }
    func getTimeline(in context: Context, completion: @escaping (Timeline<StepEntry>) -> Void) {
        // 시간별 entries
    }
}

WatchConnectivity (iPhone ↔ Watch)

import WatchConnectivity

class WCManager: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WCManager()
    override init() {
        super.init()
        if WCSession.isSupported() {
            WCSession.default.delegate = self
            WCSession.default.activate()
        }
    }
    
    func session(_ session: WCSession, activationDidCompleteWith state: WCSessionActivationState, error: Error?) {}
    
    // Receiving
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        // 즉시 처리
    }

    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        // 백그라운드 sync 가능
    }
}

// 보내기
WCSession.default.sendMessage(["action": "fetch"], replyHandler: { reply in
    // 즉시 응답
}, errorHandler: { e in print(e) })

// 또는 application context (latest snapshot)
try WCSession.default.updateApplicationContext(["count": 42])

Workout / HealthKit

import HealthKit

let store = HKHealthStore()
let config = HKWorkoutConfiguration()
config.activityType = .running
config.locationType = .outdoor

let session = try HKWorkoutSession(healthStore: store, configuration: config)
let builder = session.associatedWorkoutBuilder()
session.startActivity(with: Date())
// ... data collection
session.end()
try await builder.endCollection(at: Date())
let workout = try await builder.finishWorkout()

Always-On Display (AOD)

@Environment(\.scenePhase) var scenePhase

// scenePhase = .background → AOD
// 절제된 정보만 (핵심 숫자)
.scenePhaseAware { phase in
    if phase == .background {
        // dim, 단순화
    }
}

Crown rotation

@State var value: Double = 0

ScrollView {
    Text("\(value)").focusable()
        .digitalCrownRotation($value, from: 0, through: 100, by: 1, sensitivity: .medium, isContinuous: false)
}

Notification (rich)

class NotificationController: WKUserNotificationHostingController<NotificationView> {
    override var body: NotificationView { NotificationView() }
}

🤔 의사결정 기준

상황	권장
단순 viewer	Complication + Smart Stack
짧은 입력	음성 / digital crown
운동 추적	HealthKit + WorkoutSession
iPhone 의존 데이터	WatchConnectivity + applicationContext
대용량 동기화	transferUserInfo / file
알림 풍부	Custom notification view

❌ 안티패턴

• iOS UI 직접: 화면 작음 — 단순화.
• 30초 이상 작업: 화면 sleep. background task.
• Always-on 무절제 데이터: 배터리. dim mode.
• WCSession.sendMessage 큼: 작은 ping 만. context 사용.
• Complication 매분 갱신: 배터리. 시간별.
• Health permission 미설명: deny 자주.
• Crown 무시: 핵심 입력. 활용.

🤖 LLM 활용 힌트

• SwiftUI + WidgetKit (Complication) + WCSession 3종.
• HealthKit 표준.
• 짧고 단순 + Always-On 고려.

🔗 관련 문서

• iOS_SwiftUI_State_Property_Wrappers
• iOS_Widget_Extension
• iOS_Background_Tasks