가이드
Capacitor에서 Widget Kit 사용법
@capgo/capacitor-widget-kit 사용하기
@capgo/capacitor-widget-kit Capacitor 앱을 통해 WidgetKit과 Live Activity 경험을 두 가지 방식으로 구현할 수 있습니다:
- 프레임 전환, 탭 핫스팟, 일시정지/재생 타이머 기능이 포함된 SVG 템플릿을 렌더링합니다.
- 앱과 위젯이 JSON 세션 상태 및 비동기 메시지를 공유하면서도 위젯은 완전한 네이티브 상태를 유지합니다.
설치
bun add @capgo/capacitor-widget-kit
bunx cap sync
SVG 템플릿 사용 시점
위젯 화면을 SVG로 정의할 수 있다면 SVG 템플릿을 사용하세요. 앱에 템플릿 정의를 저장하면 네이티브 브릿지가 플레이스홀더를 해결하며, 위젯 탭을 통해 나중에 상태를 변경할 수 있습니다.
운동 타이머, 배달 상태 카드, 스포츠 점수 또는 지정된 프레임 간 전환만으로 충분한 컴팩트한 UI에 적합합니다.
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';
const { activity } = await CapgoWidgetKit.startTemplateActivity({
activityId: 'session-1',
state: {
title: 'Chest Day',
frame: 'summary',
restDurationMs: 90000,
},
definition: {
id: 'workout-card',
timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
actions: [
{
id: 'next-frame',
frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
},
{
id: 'toggle-rest',
timerMutations: [{ op: 'toggle', timerId: 'rest' }],
},
],
layouts: {
lockScreen: {
width: 100,
height: 40,
frameIdPath: 'state.frame',
frames: [
{
id: 'summary',
hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{state.title}}</text></svg>`,
},
{
id: 'timer',
hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{timers.rest.remainingText}}</text></svg>`,
},
],
},
},
},
});
앱에서 위젯 액션 처리하기
위젯 액션은 이벤트로 저장됩니다. 앱이 재개되거나 백그라운드 동기화 단계가 끝난 뒤에 이를 읽고 확인하세요.
const { events } = await CapgoWidgetKit.listTemplateEvents({
activityId: activity.activityId,
unacknowledgedOnly: true,
});
for (const event of events) {
console.log(event.actionId, event.state, event.timers);
}
await CapgoWidgetKit.acknowledgeTemplateEvents({ activityId: activity.activityId });
Full-Native 세션을 사용해야 하는 경우
위젯 UI를 Swift, Kotlin, Java로 직접 구현하는 게 더 나은 경우 full-native 세션을 사용하세요. Capacitor는 여전히 세션을 시작·중지하고, 공유 상태를 최신으로 유지하며, 앱과 위젯 code 사이의 작업을 큐에 넣습니다.
const { session } = await CapgoWidgetKit.startWidgetSession({
widgetId: 'native-session-1',
kind: 'workout-controls',
state: { isRunning: true, selectedSetId: 'set-1' },
metadata: { accent: '#00d69c' },
});
await CapgoWidgetKit.updateWidgetSession({
widgetId: session.widgetId,
merge: true,
state: { isRunning: false },
});
위젯과 앱 간 비동기 작업 큐에 넣기
메시지는 앱에서 위젯으로, 또는 위젯에서 앱으로 전달될 수 있습니다. 확인하고 완료할 때까지 대기 상태로 유지됩니다.
const { message } = await CapgoWidgetKit.sendWidgetMessage({
widgetId: session.widgetId,
direction: 'widgetToApp',
name: 'syncWorkoutSet',
payload: { setId: 'set-1' },
expectsResponse: true,
});
await CapgoWidgetKit.acknowledgeWidgetMessages({ messageIds: [message.messageId] });
await CapgoWidgetKit.completeWidgetMessage({
messageId: message.messageId,
response: { synced: true },
});
작업이 실패하면 에러와 함께 메시지를 완료하세요:
await CapgoWidgetKit.completeWidgetMessage({
messageId: message.messageId,
error: 'Sync failed',
});
세션 깔끔하게 종료하기
await CapgoWidgetKit.endTemplateActivity({
activityId: activity.activityId,
state: { title: 'Workout complete', frame: 'summary' },
});
await CapgoWidgetKit.stopWidgetSession({
widgetId: session.widgetId,
state: { isRunning: false },
});
Native 설정 참고 사항
iOS WidgetKit 및 Live Activities의 경우 앱과 위젯 extension 타겟에 App Group을 구성하고 다음을 설정하세요: CapgoWidgetKitAppGroup 양쪽 모두의 Info.plist 파일에. 대화형 버튼을 사용하려면 플러그인에서 제공하는 native bridge와 action intent를 연결하는 widget extension이 필요합니다.
전체 레퍼런스
- GitHub: https://github.com/Cap-go/capacitor-widget-kit/
- 문서: /docs/plugins/widget-kit/
@capgo/capacitor-widget-kit 사용하기 다음 단계
사용 중이라면 @capgo/capacitor-widget-kit 사용하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-widget-kit @capgo/capacitor-widget-kit의 구현 세부 사항은 시작하기 Getting Started의 구현 상세 내용은 Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor Plugins 구현 세부 사항 및 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은.