가이드
Capacitor에서 Live Activities를 사용하는 방법
@capgo/capacitor-live-activities 사용
iOS Live Activities를 관리하기 위한 Capacitor Live Activities 플러그인 인터페이스
설치
bun add @capgo/capacitor-live-activities
bunx cap sync
iOS 설정
플러그인을 설치하고 동기화하는 것만으로는 네이티브 Live Activity UI가 생성되지 않습니다. 호출하기 전에 startActivityXcode에서 ActivityKit을 구성하세요:
- 실행
bunx cap open ios. - 다음 Widget Extension 타겟을 추가하고 Include Live Activity를 활성화하세요..
- 앱과 Widget Extension의 deployment target을 iOS 16.1 이상으로 설정하세요.
- extension이 메인 앱에 포함되어 있는지 확인하세요.
- 다음 항목이
ActivityConfigurationextension의WidgetBundle에 등록된 상태로 유지되도록 하고, Lock Screen 및 모든 Dynamic Island 표시를 포함하도록 설정하세요. - 추가
NSSupportsLiveActivities메인 앱 타겟의Info.plist.
<key>NSSupportsLiveActivities</key>
<true/>
타겟만 추가해서는 충분하지 않습니다. 네이티브 앱이나 플러그인에서 ActivityKit의 request, update, end API를 호출해야 합니다. 또한 Widget Extension에는 해당 호출에서 사용하는 데이터 및 콘텐츠 상태를 디코딩하고 렌더링할 수 있는 SwiftUI code가 포함되어 있어야 합니다. ActivityAttributes 메인 앱과 Widget Extension 타겟 모두에 공유 ActivityKit 모델을 포함하세요. Xcode에서 생성된 Live Activity 템플릿은 이 플러그인에 전달된 JSON 레이아웃을 자동으로 렌더링하지 않으므로, 익스텐션에도 호환 가능한 네이티브 레이아웃 렌더러가 필요합니다.
공유 이미지
이미지 관리 메서드를 사용할 때는 App Groups 기능을 메인 앱과 Widget Extension 타겟에 추가해야 합니다. 플러그인이 요구하는 정확한 식별자를 사용하여 두 타겟 모두에서 동일한 그룹을 활성화하세요:
group.<MAIN_APP_BUNDLE_ID>.liveactivities
Live Activity extensions cannot access the network. Download remote images in the main app, save them to the shared App Group with saveImage레이아웃에서 저장된 이미지를 참조하세요. 번들된 에셋 또한 Widget Extension 타겟에 포함되어 있어야 합니다.
딥 링크 및 푸시 업데이트
- 다음에서 사용하는 모든 커스텀 URL scheme을 등록하세요:
behavior.widgetUrl또는tapUrl메인 앱 타겟의 Info > URL Types 설정에서. - 서버 주도 업데이트를 사용하려면, 푸시 알림 기능을 추가하고 APNs로 ActivityKit 푸시 토큰 처리를 구현하세요.
- 추가
NSSupportsLiveActivitiesFrequentUpdates앱에서 빈번한 ActivityKit 푸시 업데이트가 필요할 때만.
Push Notifications 기능을 활성화하는 것만으로는 충분하지 않습니다. 서버 주도 업데이트에는 네이티브 토큰 처리와 APNs 백엔드가 필요합니다.
ActivityKit은 정적 및 동적 Live Activity 데이터의 합계를 4 KB로 제한합니다. Dynamic Island는 지원되는 기기 모델에서만 표시되며, 그 외 기기에서는 잠금 화면 표시를 사용합니다.
플러그인이 제공하는 기능
areActivitiesSupported- 이 기기에서 Live Activities를 지원하는지 확인합니다. iOS 16.1 이상 및 기기 지원이 필요합니다.startActivity- 지정된 레이아웃과 데이터로 새로운 Live Activity를 시작합니다.updateActivity- 기존 Live Activity를 새로운 데이터로 업데이트합니다.endActivity- Live Activity를 종료합니다.
사용 예시
areActivitiesSupported
이 기기에서 Live Activities를 지원하는지 확인합니다. iOS 16.1 이상 및 기기 지원이 필요합니다.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
console.log('Live Activities are supported!');
} else {
console.log('Not supported:', reason);
}
startActivity
지정된 레이아웃과 데이터로 새로운 Live Activity를 시작합니다.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { activityId } = await CapgoLiveActivities.startActivity({
layout: {
type: 'container',
direction: 'horizontal',
children: [
{ type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
{ type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
]
},
dynamicIslandLayout: {
expanded: {
leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
trailing: { type: 'text', content: '{{eta}}' },
center: { type: 'text', content: '{{status}}' },
bottom: { type: 'progress', value: 'progress' }
},
compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
compactTrailing: { type: 'text', content: '{{eta}}' },
minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
},
data: {
orderNumber: '12345',
status: 'On the way',
eta: '10 min',
progress: 0.6
}
});
console.log('Started activity:', activityId);
updateActivity
기존 Live Activity를 새로운 데이터로 업데이트합니다.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.updateActivity({
activityId: 'abc123',
data: {
status: 'Arrived!',
eta: 'Now',
progress: 1.0
},
alertConfiguration: {
title: 'Delivery Update',
body: 'Your order has arrived!'
}
});
endActivity
Live Activity를 종료합니다.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.endActivity({
activityId: 'abc123',
data: { status: 'Delivered' },
dismissalPolicy: 'after',
dismissAfter: Date.now() + 3600000 // 1 hour from now
});
전체 레퍼런스
- GitHub: https://github.com/Cap-go/capacitor-live-activities/
- 문서: /docs/plugins/live-activities/
@capgo/capacitor-live-activities 사용하기에서 계속하기
사용 중이라면 @capgo/capacitor-live-activities 사용 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항, 시작하기 Getting Started의 구현 상세 내용은 @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player 사용 시 네이티브 기능은, @capgo/capacitor-video-player 구현 세부 사항은 @capgo/capacitor-video-player에서 확인하고, @capgo/capacitor-native-navigation 사용하기 @capgo/capacitor-native-navigation. 사용 시의 Native 기능