---
id: ios-live-activities
title: Live Activities — 잠금 화면 / Dynamic Island
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [ios, live-activity, activitykit, dynamic-island, vibe-coding]
tech_stack: { language: "Swift / ActivityKit", applicable_to: ["iOS 16.1+"] }
applied_in: []
aliases: [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 정의
```swift
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
}
```

### 시작 (앱 안)
```swift
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 (앱 안)
```swift
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)))
}
```

### 종료
```swift
await activity.end(activity.content, dismissalPolicy: .after(.now.addingTimeInterval(5 * 60)))
```

### Widget Extension 의 LiveActivity view
```swift
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]]