문제 해결

일반적인 문제

Live Activity가 잠금 화면에 표시되지 않습니다

원인 1: NSSupportsLiveActivities가 Info.plist에 없는 경우

ios/<프로젝트명>/Info.plist 파일에 다음 키가 있는지 확인합니다.

<key>NSSupportsLiveActivities</key>
<true/>

원인 2: iOS 버전이 16.1 미만인 경우

Live Activity는 iOS 16.1 이상에서만 동작합니다. areActivitiesEnabled()로 사용 가능 여부를 먼저 확인하세요.

const enabled = await LiveActivityManager.areActivitiesEnabled();
if (!enabled) {
  console.log('Live Activity를 사용할 수 없습니다 (iOS 16.1+ 필요)');
  return;
}

원인 3: 사용자가 Live Activity 권한을 거부한 경우

사용자가 설정에서 Live Activity를 비활성화했을 수 있습니다. 설정 > [앱 이름] > Live Activity 허용 옵션을 확인하도록 안내하세요.

원인 4: 위젯 익스텐션의 ActivityAttributes가 잘못 정의된 경우

위젯 익스텐션의 Swift ActivityAttributes 구조체가 네이티브 모듈에서 전달하는 데이터 구조와 일치하는지 확인하세요.

requestLiveActivities 호출 후 아무 일도 일어나지 않습니다 (Android)

Android는 스텁 구현을 사용하므로 정상 동작입니다. Android에서 Live Activity 기능은 지원되지 않습니다.

import { Platform } from 'react-native';

if (Platform.OS === 'ios') {
  await LiveActivityManager.requestLiveActivities(items);
} else {
  // Android에서는 별도 알림 로직 사용
}

위젯 익스텐션 빌드 오류가 발생합니다

원인 1: Deployment Target이 너무 낮은 경우

위젯 익스텐션의 최소 배포 타겟을 iOS 16.1 이상으로 설정하세요.

1. Xcode에서 위젯 익스텐션 타겟 선택
2. General > Minimum Deployments > 16.1 이상으로 설정

원인 2: ActivityKit 프레임워크가 누락된 경우

위젯 익스텐션 타겟의 Build Phases > Link Binary With Libraries에 ActivityKit.framework가 포함되어 있는지 확인하세요.

updateReceptionState 후 위젯이 업데이트되지 않습니다

원인 1: 존재하지 않는 id로 업데이트를 시도한 경우

id는 requestLiveActivities에서 사용한 id와 정확히 일치해야 합니다.

// 시작 시
await LiveActivityManager.requestLiveActivities([
  { id: 'receipt-001', ... }
]);

// 업데이트 시 동일한 id 사용
await LiveActivityManager.updateReceptionState({
  id: 'receipt-001', // 정확히 일치해야 함
  state: 'inProgress',
});

원인 2: Live Activity가 이미 종료된 경우

Live Activity는 시스템에 의해 자동으로 종료될 수 있습니다 (배터리 절약 모드, 오래된 Activity 등). requestLiveActivities를 다시 호출하여 새로운 Activity를 시작하세요.

네이티브 모듈을 찾을 수 없습니다

Error: Cannot find native module 'ReactNativeLiveActivity'

해결:

# CocoaPods 재설치
cd ios && pod install && cd ..

# 빌드 캐시 초기화
npx react-native start --reset-cache

# 앱 재빌드
npx react-native run-ios

Dynamic Island에 위젯이 표시되지 않습니다

Dynamic Island는 iPhone 14 Pro 이상에서만 지원됩니다. iPhone 14 또는 이전 모델에서는 잠금 화면에만 표시됩니다. 위젯 익스텐션에서 dynamicIsland 설정이 올바른지 확인하세요.

알려진 제한사항

Android 스텁 동작 설명

Android에서 각 메서드의 반환 동작은 다음과 같습니다.

이 동작 덕분에 플랫폼 분기 없이 동일한 코드를 사용할 수 있습니다.

// 이 코드는 iOS와 Android 모두에서 에러 없이 동작합니다
const enabled = await LiveActivityManager.areActivitiesEnabled();
if (enabled) {
  await LiveActivityManager.requestLiveActivities(items);
}
// Android에서는 enabled가 false이므로 requestLiveActivities는 호출되지 않습니다

FAQ

Q: Live Activity는 앱이 백그라운드에 있을 때도 업데이트할 수 있나요?

예. 두 가지 방법으로 업데이트할 수 있습니다.

1. 앱이 백그라운드에서 실행 중일 때 updateReceptionState 직접 호출
2. APNs(Apple Push Notification Service)를 통한 원격 업데이트

Q: Live Activity는 얼마나 오래 표시되나요?

iOS 시스템이 Live Activity를 최대 8시간 동안 표시합니다. 그 이후에는 자동으로 종료됩니다. endAllActivities()를 호출하면 즉시 종료할 수 있습니다.

Q: completed 상태로 업데이트하면 자동으로 종료되나요?

completed 상태로 업데이트해도 Live Activity가 즉시 종료되지 않습니다. 완료 상태를 표시한 후 적절한 시점에 endAllActivities()를 호출하거나 requestLiveActivities([])로 빈 배열을 전달하여 명시적으로 종료하세요.