# Expo Live Activity 타이머

By Tarik Pinarci (https://tarikpinarci.com). Published 2025-05-01. Canonical: https://tarikpinarci.com/ko/blog/expo-live-activity-timer

# Expo로 Live Activity 타이머 만들기

iOS의 Live Activities는 판도를 바꾸는 기능입니다. 앱이 잠금 화면이나 Dynamic Island에 실시간 업데이트를 바로 보여 줄 수 있게 해 주니까요. 자연스럽게 저는 거기서 운동 타이머가 돌아가면 얼마나 멋질지 상상하기 시작했습니다. 휴대폰 잠금을 풀지 않아도 사용자가 계속 의욕을 유지할 수 있을 테니까요. 하지만 함정이 있었습니다. Live Activities는 Swift와 ActivityKit 같은 Apple의 네이티브 도구로 만듭니다. 그때 모듈 전체를 처음부터 작성하는 대신 쓸 수 있는 [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets)라는 도구를 발견했고, 덕분에 과정이 예상보다 훨씬 쉬워졌습니다. 이 글에서는 제가 iOS용 타이머 기반 Live Activity를 어떻게 만들었는지, 어떤 단계를 거쳤는지, 그 과정에서 무엇을 배웠는지 소개하겠습니다.

## 제가 Live Activities에 빠진 이유

Live Activities는 그냥 멋진 기능이 아니라 사용자 참여도를 바꿔 놓는 기능입니다. Apple의 [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities)는 Live Activities를 시간에 민감한 작업에 대해 "현재 상황을 한눈에 볼 수 있는 정보"를 전달하는 방법으로 설명합니다. 운동 중에 플랭크 시간을 보여 주는 피트니스 앱, 피자가 오고 있는 여정을 추적하는 음식 배달 앱, 기사의 도착 예정 시간을 업데이트하는 차량 호출 앱이 모두 잠금 화면에, 그리고 iPhone 14 Pro 이상에서는 Dynamic Island에 바로 나타난다고 상상해 보세요. 사용자가 휴대폰 잠금을 풀 필요 없이 앱의 가장 중요한 업데이트를 볼 수 있는 VIP 패스를 주는 것과 같습니다.

저는 사용자가 세트를 하는 동안 운동 타이머가 올라가는 걸 보면서, 앱을 열지 않고도 집중할 수 있기를 바랐습니다. 앱을 프로답게 느끼게 만드는 그런 완성도였고, 저는 완전히 꽂혔습니다. 하지만 네이티브 레이어를 전혀 건드리지 않고는 이 모든 걸 처리할 수 없으니, Swift에 뛰어들어 Xcode와 씨름하게 될 거라는 걸 알았습니다. 그러다 Expo의 JavaScript 세계와 iOS의 네이티브 기능 사이의 간극을 이어 주는 패키지 [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets)를 발견했습니다. [Evan Bacon](https://x.com/Baconbrix)에게 큰 박수를 보냅니다. 이 도구 덕분에 막막한 작업이 어렵지만 풀 수 있는 퍼즐처럼 느껴졌습니다.

## 큰 그림: Expo 앱 속의 Live Activities

Live Activities는 iOS만의 파티입니다. Swift 기반 프레임워크인 ActivityKit으로 동작하므로, 좋든 싫든 네이티브 코드를 작성해야 합니다. Expo 앱에서 이건 물고기에게 나무를 타라고 설득하는 것과 비슷합니다. 가능은 하지만 꽤 노력이 듭니다. expo-apple-targets는 노련한 가이드처럼 나서서, 처음부터 시작하지 않고도 네이티브 모듈과 위젯 익스텐션을 만들 수 있는 틀을 제공합니다. Swift로 네이티브 코드를 작성하고 JavaScript에 노출할 수 있게 해 주는 Expo 모듈 시스템([Expo Modules API](https://docs.expo.dev/modules/module-api/)) 위에 만들어져 있어서, 전체 과정이 신경 치료처럼 괴롭게 느껴지지 않습니다.

## 프로젝트 설정하기

시작이 아주 쉽지는 않았지만, expo-apple-targets 덕분에 감당할 만했습니다. 제가 시작한 방법은 이렇습니다.

- **expo-apple-targets 설치**: npm install expo-apple-targets 한 번으로 출발했습니다. 패키지의 README는 보물창고입니다. Xcode에서 위젯 익스텐션을 추가하고 app.json에 Live Activity entitlement(com.apple.developer.activitykit)를 추가하는 과정을 안내해 줍니다.

- **네이티브 모듈 설정**: Expo의 모듈 시스템으로 ActivityKit과 통신하는 Swift 모듈을 만들었습니다. [Expo Modules 문서](https://docs.expo.dev/modules/module-api/)는 함수 시그니처와 이벤트를 명확하게 정의하라고 강조하는데, 덕분에 startActivity 같은 메서드를 큰 어려움 없이 JavaScript에 노출할 수 있었습니다.

- **위젯 익스텐션**: 여기서 SwiftUI가 등장합니다. 잠금 화면과 Dynamic Island에 나타날 Live Activity의 모습을 SwiftUI로 디자인했습니다. expo-apple-targets가 위젯 템플릿을 제공하지만, 째깍거리는 타이머와 인터랙티브 버튼을 보여 주도록 직접 손봐야 했습니다.

- **인텐트**: 사용자가 위젯의 버튼을 탭해 타이머를 일시정지하거나 다시 시작할 수 있게 해 줍니다. expo-apple-targets가 인텐트 설정을 단순하게 해 주지만, 알림이 제대로 흐르게 하려면 몇 번의 오작동을 디버깅해야 했습니다.

## 매초 업데이트되는 타이머?

![한 개발자가 신나서 1초마다 업데이트되는 타이머를 구현하고, 타이머가 난동을 부리며 시스템이 혼란스럽게 과부하에 걸리는 모습. ([gpt-4o로 생성](https://openai.com/index/hello-gpt-4o/))](https://cdn-images-1.medium.com/max/2048/1*Nq1a3rqsEIBCgTsAWdvgNQ.png)_한 개발자가 신나서 1초마다 업데이트되는 타이머를 구현하고, 타이머가 난동을 부리며 시스템이 혼란스럽게 과부하에 걸리는 모습. ([gpt-4o로 생성](https://openai.com/index/hello-gpt-4o/))_

처음 타이머를 다룰 때 제 머리는 "_그냥 매초 현재 시간으로 Live Activity를 업데이트하면 되지_"라고 말했습니다. 간단해 보이죠? 틀렸습니다. 우연히 개발자들이 Live Activity 타이머를 업데이트하는 방법을 두고 이야기하는 [Reddit 스레드](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173)를 발견했습니다. 결론은 만장일치였습니다. 매초 업데이트하는 건 재앙입니다. 햄스터 쳇바퀴로 우주선을 움직이려는 것과 같습니다. 움직이기는 하겠지만 금방 타 버립니다. 끊임없는 업데이트는 CPU를 혹사시키고 배터리를 빨아들여 앱을 느리게 만듭니다.

그 Reddit 스레드가 정신을 번쩍 들게 했습니다. Apple의 [SwiftUI 문서](<https://developer.apple.com/documentation/swiftui/text/init(timerinterval:pausetime:countsdown:showshours:)>)에서 SwiftUI의 Text(timerInterval:)을 찾았는데, 그야말로 계시였습니다. 이 뷰는 타이머 업데이트를 네이티브로 처리해서, Live Activity 전체를 새로 고칠 필요 없이 혼자 째깍거립니다. 지루한 일은 iOS에 맡기고 재미있는 부분에 집중하는 셈입니다.

그래서 매초 업데이트 계획은 버리고 startedAt/pausedAt 방식을 택했습니다. 이 방식이 좋은 이유는 이렇습니다.

- **성능**: 매초 업데이트를 쏘는 대신 타이머의 시작 시간(startedAt)과, 일시정지했다면 일시정지 시간(pausedAt)을 저장합니다. 위젯은 Text(timerInterval:)로 startedAt을 기준으로 살아 있는 타이머를 보여 주고, 일시정지 상태에서는 pausedAt을 이용해 고정된 시간을 보여 줍니다. API 호출이 거의 0으로 줄어듭니다.

- **배터리 효율**: 잦은 업데이트는 배터리 흡혈귀입니다. 째깍거리는 일을 SwiftUI에 맡기면 앱이 가벼워지고 사용자의 휴대폰도 행복해집니다.

- **API 준수**: Apple의 Live Activity API는 실시간으로 업데이트를 쏟아붓도록 만들어지지 않았습니다. startedAt/pausedAt 구조는 iOS가 기대하는 방식과 잘 맞아서 호출 제한에 걸릴 가능성을 줄여 줍니다.

- **코드 단순성**: 타임스탬프 두 개를 관리하는 건 업데이트 흐름을 저글링하는 것보다 훨씬 쉽습니다. 코드도 깔끔하고 제 스트레스도 관리됩니다.

이 방식은 비디오 게임에서 비밀 지름길을 찾은 기분이었습니다. 타이머는 부드럽게 돌아가고, 보기에도 좋고, 자원을 독차지하지도 않습니다. 저를 올바른 방향으로 이끌어 준 그 Reddit 스레드([다시 한번 링크](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173))는 훈장을 받을 만합니다.

## Live Activity의 핵심

코드 한 줄 한 줄로 지루하게 만들지는 않겠습니다. 이 타이머를 움직이는 핵심 코드에 집중해 봅시다. 전체 소스 코드는 글 마지막에 GitHub으로 공유하겠습니다.

### LiveActivityAttributes 구조체

이 구조체는 Live Activity의 뼈대로, 데이터와 그 데이터가 어떻게 변하는지를 정의합니다.

```swift
    struct LiveActivityAttributes: ActivityAttributes {
      public struct ContentState: Codable, Hashable {
        var startedAt: Date
        var pausedAt: Date?

        func getElapsedTimeInSeconds() -> TimeInterval {
          if let pausedAt = pausedAt {
            return pausedAt.timeIntervalSince(startedAt)
          } else {
            return Date().timeIntervalSince(startedAt)
          }
        }
        func isRunning() -> Bool {
          return pausedAt == nil
        }
        func getFormattedElapsedTime() -> String {
          let elapsed = getElapsedTimeInSeconds()
          let totalSeconds = Int(elapsed)
          let hours = totalSeconds / 3600
          let minutes = (totalSeconds % 3600) / 60
          let seconds = totalSeconds % 60
          if hours > 0 {
            return String(format: "%d:%02d:%02d", hours, minutes, seconds)
          } else {
            return String(format: "%d:%02d", minutes, seconds)
          }
        }
        func getFutureDate() -> Date {
          return Date().addingTimeInterval(365 * 24 * 60 * 60)
        }
      }
      var activityName: String
      var activityIcon: String
    }
```

이건 Live Activity의 DNA 같은 것입니다. 바깥쪽 LiveActivityAttributes는 activity가 시작될 때 정해지는 activityName(예: "Workout")과 activityIcon(예: "RUNNING") 같은 고정 데이터를 담습니다. 안쪽 ContentState는 실제 일이 일어나는 곳으로, startedAt(타이머가 시작된 시간)과 pausedAt(일시정지했다면 그 시간)을 추적합니다. 헬퍼 메서드들이 진짜 MVP입니다.

- getElapsedTimeInSeconds()는 타이머가 얼마나 오래 돌았는지 계산합니다. 일시정지 상태면 pausedAt에서 멈추고, 동작 중이면 현재 시간을 씁니다. 로직을 탄탄하고 재사용 가능하게 유지해 줍니다.

- isRunning()은 간단한 확인입니다. pausedAt이 null이면 타이머가 동작 중입니다. 다른 곳에서 지저분한 상태 확인을 피하는 깔끔한 방법입니다.

- getFormattedElapsedTime()은 초를 위젯에 쓸 보기 좋은 "MM:SS" 또는 "HH:MM:SS" 문자열로 바꿉니다. 마라톤처럼 아주 긴 운동을 하는 사용자도 있을 수 있다는 걸 깨닫고 시간 단위를 추가했습니다.

- getFutureDate()는 1년 뒤의 날짜를 만듭니다. 이 날짜를 Text(timerInterval:)에 넘겨서 종료 날짜를 걱정하지 않고 타이머가 계속 돌게 합니다.

이 구조체가 모든 걸 정돈해 주는 점이 좋습니다. 잘 싼 배낭처럼 필요한 건 다 있고, 필요 없는 건 하나도 없습니다. Codable과 Hashable을 준수하므로 업데이트를 위해 직렬화하기도, SwiftUI에서 쓰기도 쉬운데, 모듈과 위젯 사이에서 상태를 동기화할 때 큰 도움이 되었습니다.

### Live Activity 시작하기

startActivity 함수에서 마법이 시작되어 새 Live Activity가 시작됩니다.

```swift
    AsyncFunction("startActivity") { (activityName: String, activityIcon: String) -> String in
        if #available(iOS 16.2, *) {
            await self.endAllActivities()
            self.startedAt = Date()
            self.pausedAt = nil
            if !ActivityAuthorizationInfo().areActivitiesEnabled {
                return ""
            }
            let attributes = LiveActivityAttributes(activityName: activityName, activityIcon: activityIcon)
            let contentState = LiveActivityAttributes.ContentState(startedAt: self.startedAt!, pausedAt: nil)
            do {
                let activity = try Activity.request(attributes: attributes, content: .init(state: contentState, staleDate: nil), pushType: nil)
                self.currentActivityId = activity.id
                self.sendTimerUpdateEvent()
                return activity.id
            } catch {
                throw error
            }
        }
        return ""
    }
```

이 함수는 불을 붙이는 불꽃입니다. Expo의 모듈 시스템을 통해 JavaScript에 노출되므로, React Native 앱에서 이름과 아이콘을 넘겨 호출할 수 있습니다. 하는 일은 이렇습니다.

- iOS 16.2 이상인지 확인합니다. 그 전 버전에는 Live Activities가 없습니다.

- endAllActivities()를 호출해 기존 activity를 모두 정리합니다. iOS는 여러 Live Activity를 허용하지만, 혼란을 피하려고 한 번에 하나만 두고 싶었습니다.

- startedAt을 현재 시간으로 설정하고 pausedAt을 비워 타이머가 돌 준비를 합니다.

- Live Activities가 활성화되어 있는지 확인합니다(사용자가 설정에서 끌 수 있는데, 초반에 이것 때문에 꽤 헤맸습니다).

- 전달받은 이름과 아이콘으로 LiveActivityAttributes를, 시작 시간으로 ContentState를 만듭니다.

- Activity.request로 새 activity를 요청하면 고유 ID를 가진 Activity 객체를 받습니다.

- ID를 저장하고, JavaScript에 업데이트 이벤트를 보내고, 앱이 추적할 수 있도록 ID를 반환합니다.

### 타이머 일시정지하기

타이머 일시정지는 Live Activity의 상태를 업데이트하는 performPause가 처리합니다.

```swift
    private func performPause(activityId: String?) async -> Bool {
        guard #available(iOS 16.2, *), self.pausedAt == nil else {
            return false
        }
        let targetId = activityId ?? self.currentActivityId
        guard let targetId = targetId else {
            return false
        }
        guard let activity = await self.findActivityById(targetId) else {
            return false
        }
        guard let currentStartedAt = self.startedAt else {
            return false
        }
        let now = Date()
        self.pausedAt = now
        let contentState = LiveActivityAttributes.ContentState(startedAt: currentStartedAt, pausedAt: self.pausedAt)
        await activity.update(using: contentState)
        self.sendTimerUpdateEvent()
        return true
    }
```

여기서 startedAt/pausedAt 방식이 빛을 발합니다. 사용자가 (앱이나 위젯에서) 타이머를 일시정지하면 이 함수는 다음을 합니다.

- iOS 16.2 이상인지, 타이머가 이미 일시정지 상태가 아닌지 확인합니다(두 번 일시정지는 안 됩니다).

- activity ID를 가져오고, 없으면 currentActivityId를 씁니다.

- 활성 activity를 뒤지는 findActivityById로 activity를 찾습니다.

- pausedAt을 현재 시간으로 설정해 타이머를 멈춥니다.

- 원래 startedAt과 새 pausedAt으로 새 ContentState를 만듭니다.

- activity.update로 activity를 업데이트해 위젯이 일시정지된 시간을 보여 주게 합니다.

- 앱 UI가 동기화되도록 JavaScript에 이벤트를 보냅니다.

여기서 로직의 핵심은 정확성입니다. 모든 확인(pausedAt == nil 같은)은 존재하지 않는 activity를 일시정지하는 것 같은 이상한 엣지 케이스를 막기 위해 있습니다. 이벤트 처리는 [Expo Modules 문서](https://docs.expo.dev/modules/overview/)에 기대어 sendEvent로 JavaScript에 업데이트를 보냈습니다. 이 함수의 초기 버전은 startedAt을 검증하지 않아서 타이머가 이상하게 표시되곤 했습니다. 교훈: 상태는 항상 guard로 지키세요.

## 잠금 화면 뷰

LockScreenLiveActivityView는 휴대폰이 잠겨 있을 때 사용자가 보는 화면이라 근사해 보여야 합니다.

![잠금 화면 Live Activity](https://cdn-images-1.medium.com/max/2000/1*IZ1ZSG7_99jfTMBJosePGQ.png)_잠금 화면 Live Activity_

```swift
    struct LockScreenLiveActivityView: View {
        let context: ActivityViewContext<LiveActivityAttributes>
        var body: some View {
            ZStack {
                Color.black.opacity(0.8)
                    .clipShape(RoundedRectangle(cornerRadius: 16))
                HStack(spacing: 16) {
                    VStack(alignment: .leading, spacing: 12) {
                        HStack(spacing: 8) {
                            ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                                        themeColor: .white,
                                        size: 18)
                            Text(context.attributes.activityName)
                                .font(.headline)
                                .foregroundColor(.white)
                        }
                        VStack(alignment: .leading, spacing: 4) {
                            if !context.state.isRunning() {
                                Text(context.state.getFormattedElapsedTime())
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            } else {
                                Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                                     pauseTime: nil,
                                     countsDown: false,
                                     showsHours: false)
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            }
                        }
                    }
                    .frame(maxHeight: .infinity, alignment: .center)
                    Spacer()
                    VStack {
                        Spacer()
                        if context.state.isRunning() {
                            Button(intent: PauseIntent()) {
                                ZStack {
                                    Circle()
                                        .fill(Color(hex: "#007bff"))
                                        .frame(width: 44, height: 44)
                                    Image(systemName: "pause.fill")
                                        .font(.system(size: 18, weight: .bold))
                                        .foregroundColor(.white)
                                }
                            }
                            .buttonStyle(PlainButtonStyle())
                        } else {
                            HStack(spacing: 8) {
                                Button(intent: CompleteIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#28a745"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "checkmark")
                                            .font(.system(size: 16, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                                Button(intent: ResumeIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#007bff"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "play.fill")
                                            .font(.system(size: 18, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                            }
                        }
                        Spacer()
                    }
                }
                .padding(16)
            }
        }
    }
```

이 뷰가 Live Activity의 시각적인 심장이고, SwiftUI가 진가를 발휘하는 곳입니다. 뷰는 양쪽으로 나뉩니다.

- **왼쪽**: activity 이름, 아이콘, 타이머를 보여 줍니다. 타이머가 동작 중이면 Text(timerInterval:)가 힘든 일을 맡아 startedAt부터 (getFutureDate 덕분에) 1년 뒤까지 숫자를 올립니다. 일시정지 상태면 getFormattedElapsedTime의 고정된 시간을 보여 줍니다. .monospacedDigit() modifier가 숫자를 또렷하게 유지해 주고, 굵고 읽기 쉽게 폰트도 조정했습니다.

- **오른쪽**: 버튼을 담당합니다. 동작 중에는 파란색 일시정지 버튼이 있습니다. 일시정지 상태에서는 앱을 여는 초록색 체크 표시와 다시 시작하는 파란색 재생 버튼이 나옵니다. 각 버튼은 인텐트를 실행하고, 네이티브 모듈이 이를 받아 처리합니다.

## [Dynamic Island](https://developer.apple.com/design/human-interface-guidelines/live-activities#The-Dynamic-Island) 살펴보기

![Dynamic Island 뷰](https://cdn-images-1.medium.com/max/2000/1*iqy0d6FZe9UU0Tce7qCDug.png)_Dynamic Island 뷰_

이 코드는 Live Activity가 Dynamic Island의 세 가지 모드, 즉 expanded(전체 보기), compact(축소), minimal(최소)에서 어떻게 보일지 정의합니다.

```swift
    dynamicIsland: { context in
      DynamicIsland {
        DynamicIslandExpandedRegion(.leading) {
          VStack(alignment: .leading, spacing: 8) {
            HStack(spacing: 8) {
              ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                          themeColor: .white,
                          size: 18)

              Text(context.attributes.activityName)
                .foregroundColor(.white)
                .font(.system(size: 16, weight: .semibold))
            }

            if !context.state.isRunning() {
              Text(context.state.getFormattedElapsedTime())
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            } else {
              Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                   pauseTime: nil,
                   countsDown: false,
                   showsHours: false)
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            }
          }
          .padding(.leading, 8)
        }

        DynamicIslandExpandedRegion(.trailing) {
          VStack {
            Spacer()

            if context.state.isRunning() {
              Button(intent: PauseIntent()) {
                ZStack {
                  Circle()
                    .fill(Color(hex: "#007bff"))
                    .frame(width: 44, height: 44)
                  Image(systemName: "pause.fill")
                    .font(.system(size: 18, weight: .bold))
                    .foregroundColor(.white)
                }
              }
              .buttonStyle(PlainButtonStyle())
              .padding(.horizontal, 8)
            } else {
              HStack(spacing: 8) {
                Button(intent: CompleteIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#28a745"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "checkmark")
                      .font(.system(size: 16, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())

                Button(intent: ResumeIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#007bff"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "play.fill")
                      .font(.system(size: 18, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())
              }
            }
          }
          .frame(maxHeight: .infinity)
        }
      } compactLeading: {
        HStack(spacing: 4) {
          ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                      themeColor: .white,
                      size: 16)

          Text(context.attributes.activityName)
            .foregroundColor(.white)
            .font(.system(size: 12))
            .lineLimit(1)
            .truncationMode(.tail)
        }
      } compactTrailing: {
        if !context.state.isRunning() {
          Text(context.state.getFormattedElapsedTime())
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        } else {
          Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
               pauseTime: nil,
               countsDown: false,
               showsHours: false)
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        }
      } minimal: {
        ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                    themeColor: .white,
                    size: 12)
      }
    }
```

- [\*\*Expanded 모드](https://developer.apple.com/design/human-interface-guidelines/live-activities#Expanded-presentation)\*\*: 길게 누르면 나타나며 .leading과 .trailing으로 나뉩니다. leading 쪽에는 아이콘(예: 달리는 사람)과 이름("Workout")이 쌓이고, 큰 타이머가 있습니다. 일시정지 상태면 고정된 시간(getFormattedElapsedTime), 동작 중이면 째깍거리는 시간(Text(timerInterval:))입니다. trailing 쪽에는 버튼이 있습니다. 동작 중에는 파란색 일시정지 버튼, 일시정지 상태에서는 초록색 체크 표시(앱 열기)와 파란색 재생(다시 시작)입니다. Island의 곡선에 맞게 폰트와 패딩을 조정했습니다.

- [\*\*Compact 모드](https://developer.apple.com/design/human-interface-guidelines/live-activities#Compact-presentation)\*\*: 공간이 줄어들면 compactLeading에는 작은 아이콘과 잘린 이름이, compactTrailing에는 타이머(고정 또는 째깍거림)가 표시됩니다. .lineLimit(1)이 이름을 깔끔하게 유지하고, 12포인트 폰트로 가독성을 확보합니다.

- [\*\*Minimal 모드](https://developer.apple.com/design/human-interface-guidelines/live-activities#Minimal-presentation)\*\*: 아주 좁은 공간이라 덤벨 같은 12포인트 아이콘 하나만 보여 주며 "타이머 아직 돌고 있어요"라고 알려 줍니다. 단순하지만 효과적입니다.

## \_shared 폴더: 왜 중요한가

![_shared 폴더 개요](https://cdn-images-1.medium.com/max/2000/1*OdZlqw2AXJeTakpTlghLDQ.png)_\_shared 폴더 개요_

[expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets?tab=readme-ov-file#_shared)의 \_shared 폴더는 핵심 코드를 메인 앱 타깃과 Live Activity 위젯 같은 하위 타깃 양쪽에 연결하도록 설계된 최상위 디렉터리입니다.

위젯 같은 익스텐션은 별도 프로세스에서 동작하므로, 특정 파일을 메인 앱의 타깃뿐 아니라 익스텐션의 타깃에도 연결해야 합니다. \_shared 폴더는 이런 파일들이 양쪽에 자동으로 연결되게 해서 수동 설정을 없애 줍니다. 제 타이머의 경우 LiveActivityAttributes 구조체를 여기에 두어서, 앱과 위젯이 동기화 문제 없이 같은 타이머 상태(startedAt, pausedAt)를 공유하도록 보장했습니다.

## Live Activity 위젯에서 앱 실행하기

CompleteIntent는 사용자가 Live Activity 위젯의 체크 버튼을 탭해 앱을 열 수 있게 해 주며, 타이머를 끝냈다는 신호가 됩니다. 운동을 마무리하는 단순하지만 중요한 상호작용입니다.

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct CompleteIntent: AppIntent, LiveActivityIntent {
        static var title: LocalizedStringResource = "Complete Exercise"
        static var description: IntentDescription = "Opens the app to complete the exercise"
        static var openAppWhenRun: Bool = true

        init() {}
        func perform() async throws -> some IntentResult {
            NotificationCenter.default.post(name: Notification.Name("completeActivityFromWidget"), object: nil)

            return .result()
        }
    }
```

사용자가 초록색 체크 표시를 탭하면 이 인텐트가 실행되어 completeActivityFromWidget 알림을 보냅니다. 네이티브 모듈이 이를 받아 JavaScript에 onWidgetCompleteActivity 이벤트를 보내고, [openAppWhenRun](https://developer.apple.com/documentation/appintents/openurlintent/openappwhenrun): true 덕분에 iOS가 앱을 엽니다.

## 인텐트로 사용자 탭 처리하기

PauseIntent는 위젯을 인터랙티브하게 만들어 주는 인텐트 중 하나입니다.

![잠금 화면 Live Activity 인텐트](https://cdn-images-1.medium.com/max/2000/1*k2nzvHgwgqj6tFESIFcmbw.png)_잠금 화면 Live Activity 인텐트_

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct PauseIntent: AppIntent, LiveActivityIntent {
      static var title: LocalizedStringResource = "Pause Timer"
      static var description: IntentDescription = "Pauses the current timer."

      init() {}

      func perform() async throws -> some IntentResult {
        NotificationCenter.default.post(name: Notification.Name("pauseTimerFromWidget"), object: nil)
        return .result()
      }
    }
```

이 인텐트는 사용자가 위젯의 일시정지 버튼을 탭하면 실행됩니다. 아주 단순하지만 강력합니다.

- 네이티브 모듈이 setupNotificationObservers로 받는 알림(pauseTimerFromWidget)을 보냅니다.

- 그러면 모듈이 performPause를 실행해 Live Activity의 상태를 업데이트하고 JavaScript에 알립니다.

이 구조의 아름다움은 인텐트가 매끄러운 순환을 만든다는 점입니다. 사용자 탭 → 인텐트 실행 → 모듈 업데이트 → 앱 동기화. expo-apple-targets가 템플릿을 제공해 인텐트 설정은 식은 죽 먹기였지만, 탭이 인식되지 않는 경우를 하나 디버깅해야 했습니다. 알고 보니 알림 이름에 오타가 있었습니다. 고전적이죠. [Expo Modules 문서](https://docs.expo.dev/modules/overview/)는 네이티브 동작으로 발생한 이벤트를 처리하는 방법을 이해하는 데 도움이 되었고, 이것이 기능을 동작하게 만드는 핵심이었습니다.

## JavaScript와 대화하는 이벤트

![](https://cdn-images-1.medium.com/max/2000/1*F5GUBNYqWxbZbLU8-LZ0Ug.png)

다음 섹션의 이벤트들은 네이티브 모듈이 Expo의 이벤트 시스템을 이용해 React Native 앱을 Live Activity의 상태와 동기화하는 방법입니다.

### onWidgetCompleteActivity

이 이벤트는 사용자가 체크 표시를 탭해 activity를 완료할 때, CompleteIntent에 의해 발생합니다.

```swift
    @objc func completeIntentHandler(_ notification: Notification) {
        guard let currentId = self.currentActivityId, self.startedAt != nil else {
            return
        }

        let elapsed = self.calculateElapsedTime()

        sendEvent("onWidgetCompleteActivity", [
            "activityId": currentId,
            "elapsedTime": Int(elapsed)
        ])
    }
```

completeIntentHandler가 completeActivityFromWidget 알림을 받아 경과 시간을 계산하고, activity ID와 경과 초를 담아 JavaScript에 onWidgetCompleteActivity 이벤트를 보냅니다. 그러면 JavaScript는 앱의 UI를 업데이트하거나 운동 완료를 기록할 수 있습니다

### onLiveActivityUpdate

이 이벤트는 타이머 상태가 바뀔 때마다(예: 일시정지, 다시 시작) 발생합니다.

```swift
    private func sendTimerUpdateEvent() {
        guard let currentId = self.currentActivityId else { return }
        guard self.startedAt != nil else { return }

        let state = self.pausedAt == nil ? "active" : "paused"
        let elapsed = self.calculateElapsedTime()

        sendEvent("onLiveActivityUpdate", [
            "state": state,
            "elapsedTime": Int(elapsed),
            "activityId": currentId
        ])
    }
```

상태가 바뀐 뒤(performPause나 performResume 안에서처럼) 호출되며, 현재 상태("active" 또는 "paused"), 경과 시간, activity ID를 담아 onLiveActivityUpdate 이벤트를 보냅니다. JavaScript는 이 이벤트를 받아 앱의 타이머 UI를 위젯과 동기화합니다.

두 이벤트는 네이티브 모듈과 JavaScript 사이에 촘촘한 피드백 루프를 만듭니다.

## 이 모든 것이 중요한 이유

이 Live Activity는 그냥 타이머가 아닙니다. 제 앱을 진짜 iOS 시민처럼 느끼게 만들어 주는 기능입니다. 중요한 이유는 이렇습니다.

- **사용자 참여**: 잠금 화면이나 Dynamic Island에 타이머를 보여 주면 사용자가 흐름을 끊지 않고 앱과 계속 연결됩니다. 1초가 중요한 운동에 딱 맞습니다.

- **네이티브 완성도**: 위젯의 깔끔한 디자인과 인터랙티브 버튼 덕분에 앱이 크로스 플랫폼으로 대충 만든 것이 아니라 원래 iOS에 속한 것처럼 느껴집니다.

- **성능**: Text(timerInterval:)를 활용한 startedAt/pausedAt 방식 덕분에 타이머가 배터리를 소모하거나 API 제한에 걸리지 않고 부드럽게 돌아갑니다.

expo-apple-targets와 [Expo Modules API](https://docs.expo.dev/modules/module-api/)는 JavaScript와 Swift를 잇는 탄탄한 틀을 제공한, 여기서의 숨은 영웅이었습니다. 깔끔한 함수 정의와 이벤트 처리를 강조하는 문서 덕분에 코드를 정돈되고 유지보수하기 좋게 유지할 수 있었습니다.

## 마무리

이 Live Activity는 잠금 화면과 Dynamic Island에 실시간 업데이트를 바로 보여 주며 앱에 부드럽고 네이티브한 느낌을 더해 줍니다. expo-apple-targets, Expo Modules API, 그리고 커뮤니티의 통찰(네, Reddit 스레드 포함) 덕분에 이것을 구현하는 과정은 꽤 수월했습니다. Live Activities는 앱을 더 연결되어 있고 역동적으로 느끼게 만드는 강력한 방법입니다

전체 소스 저장소의 GitHub 링크는 여기 있습니다 👉🏻 [https://github.com/tarikfp/expo-live-activity-timer](https://github.com/tarikfp/expo-live-activity-timer)

