2nd/10_Wiki/Topics/Coding/iOS_Live_Activities.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-live-activities	Live Activities — 잠금 화면 / Dynamic Island	Coding	draft	B	conceptual	2026-05-09	2026-05-09	ios live-activity activitykit dynamic-island vibe-coding	language applicable_to Swift / ActivityKit iOS 16.1+		ActivityKit Dynamic Island lock screen widget push to update

iOS Live Activities

잠금 화면 + Dynamic Island 에 실시간 상태. 배달 / 운동 / 스포츠 등. 앱 안에서 시작, 서버 push 또는 앱이 update. 8시간 제한.

📖 핵심 개념

• ActivityKit (iOS 16.1+).
• ActivityAttributes: 정적 (시작 시 한 번).
• ContentState: 동적 (자주 변경).
• 시작 = 앱에서 Activity.request().
• update = 앱에서 또는 push (ActivityKit push).

💻 코드 패턴

Activity 정의

import ActivityKit

struct DeliveryAttributes: ActivityAttributes {
    public typealias DeliveryStatus = ContentState

    public struct ContentState: Codable, Hashable {
        let stage: String      // 'preparing' / 'on_way' / 'delivered'
        let etaMinutes: Int
    }

    let orderNumber: String
    let restaurantName: String
}

시작 (앱 안)

import ActivityKit

func startDeliveryActivity(orderNumber: String, restaurant: String) async throws {
    let attributes = DeliveryAttributes(orderNumber: orderNumber, restaurantName: restaurant)
    let initialState = DeliveryAttributes.ContentState(stage: "preparing", etaMinutes: 30)

    let activity = try Activity.request(
        attributes: attributes,
        content: .init(state: initialState, staleDate: nil),
        pushType: .token // 서버 푸시로 업데이트할 거면
    )

    // Push token (서버에 등록)
    Task {
        for await tokenData in activity.pushTokenUpdates {
            let token = tokenData.map { String(format: "%02x", $0) }.joined()
            await api.registerLiveActivityToken(token, activityId: activity.id)
        }
    }
}

Update (앱 안)

func updateDelivery(stage: String, eta: Int) async {
    guard let activity = Activity<DeliveryAttributes>.activities.first else { return }
    let newState = DeliveryAttributes.ContentState(stage: stage, etaMinutes: eta)
    await activity.update(.init(state: newState, staleDate: .now.addingTimeInterval(60)))
}

종료

await activity.end(activity.content, dismissalPolicy: .after(.now.addingTimeInterval(5 * 60)))

Widget Extension 의 LiveActivity view

import WidgetKit
import SwiftUI

struct DeliveryWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            // 잠금 화면 view
            VStack(alignment: .leading) {
                Text(context.attributes.restaurantName).bold()
                Text("\(context.state.stage) · \(context.state.etaMinutes)분")
            }
            .padding()
            .activityBackgroundTint(.black)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) { Text("🛵") }
                DynamicIslandExpandedRegion(.trailing) { Text("\(context.state.etaMinutes)분") }
                DynamicIslandExpandedRegion(.bottom) { Text(context.state.stage) }
            } compactLeading: {
                Text("🛵")
            } compactTrailing: {
                Text("\(context.state.etaMinutes)분")
            } minimal: {
                Text("🛵")
            }
        }
    }
}

서버 push (ActivityKit push)

• APNs liveactivity topic.
• payload: event: 'update' | 'end' + content-state.

🤔 의사결정 기준

사용처	적합
음식 배달, ride share	✅
운동 timer	✅
라이브 스포츠 점수	✅
일반 알림 (메시지)	❌ — 일반 push
8시간 이상 작업	❌ — 만료
개인 / 민감 정보	잠금 화면 노출 — 검토

❌ 안티패턴

• start 후 update 무한: 8시간 제한 + push budget. 의미 있을 때만.
• 너무 잦은 update (초당): 배터리. 분 단위.
• end 안 함: 8시간 후 자동 만료, 사용자 confused.
• staleDate 없음: stale 표시 안 됨.
• Widget extension 없이: ActivityConfiguration 못 등록.
• 테스트 안 함: simulator 잘 동작. Real device 권장.

🤖 LLM 활용 힌트

• attributes (정적) + state (동적) 분리.
• iOS 16.1+, push 또는 in-app update.

🔗 관련 문서

• iOS_Widget_Extension
• iOS_Push_Notifications