시작하기

설치

bun add @capgo/capacitor-widget-kit
bunx cap sync

수입

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

iOS 설정

가능한 경우 Live Activity 버튼을 상호 작용할 수 있도록 iOS 17+를 사용하세요.

• Add
• 앱에 추가 NSSupportsLiveActivities ActivityKit을 사용할 때 Info.plist ActivityKit을 사용할 때
• 같은 App Group을 앱 대상과 위젯 확장 대상에 추가하세요.
• 설정 CapgoWidgetKitAppGroup 두 파일 모두 Info.plist 공유 App Group 식별자로 설정하세요.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

복사

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

복사

제목이 "1. SVG 템플릿 활동"인 섹션

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

앱에서 액션 실행

자연스러운 위젯은 핫스팟/액션 연결을 통해 동일한 액션을 트리거할 수 있습니다. 앱은 직접 실행할 수도 있습니다:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

위젯 이벤트 처리

클립보드 복사

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

클립보드 복사

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

액션

활성 프레임 id를 상태에 기록합니다. 레이아웃은 그 후에 이를 읽을 수 있습니다. frameIdPath.

작업	행동
set	특정 프레임 id를 설정합니다. 평범한 문자열은 Literal 프레임 id로 처리되며, 템플릿은 먼저 해결됩니다. {{...}} 다음 프레임으로 이동
next	또는 선언된 프레임 frameIds 이전 프레임으로 이동 surface.
previous	현재 프레임과 첫 번째 두 개의 프레임 또는 현재 프레임과
toggle	알려진 선택 가능한 프레임 목록이 있는 변형이 알려진 프레임 id를 무시할 때, 상태는 렌더링된 표면과 동기화됩니다. frameId.

타이머 변형

Operation

타이머 변형은 이름이 지정된 타이머를 대상으로 합니다. definition.timers.

작업	행동
start / restart	현재 지속 시간을 기준으로 0부터 시작합니다.
pause	누적 시간을 저장하고 지우세요. startedAt.
resume	일시 정지된 타이머만 재개합니다. 중단된 타이머는 명시적 시작 또는 재시작을 기다립니다.
toggle	실행 중인 타이머를 일시 정지하거나 일시 정지된 타이머를 재개하세요.
reset	누적 시간을 지우고 비활성 상태로 돌아가세요.
stop	타이머가 중단되었음을 표시하고 진행 상황을 지우세요.
setDuration	지속 시간 변경 후 상태를 재계산하세요.

SVG에서 타이머 바인딩이 사용 가능합니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}__, 그리고 관련 필드.__

Option 2: Native 위젯 세션

이 모드를 사용할 때 위젯 UI는 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 { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

비동기 위젯 메시지

메시지는 응답이 필요할 때 작업을 처리합니다. 예를 들어 위젯이 앱으로부터 데이터를 동기화하도록 요청할 때입니다.

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 },
});

작업을 실패시키려면 ‘__CAPGO_KEEP_1__’ 대신 ‘__CAPGO_KEEP_2__’를 사용하세요. error __CAPGO_KEEP_3__ 대신 ‘__CAPGO_KEEP_4__’를 사용하세요. response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage 중복 호출이 idempotent합니다. 메시지가 이미 완료되거나 실패한 경우, 반복 호출은 기존 메시지 스냅샷을 반환합니다.

네이티브 세션 중지

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API Groups

능력	SVG 활동 생명 주기
SVG 액션 및 이벤트	areActivitiesSupported, getPluginVersion
네이티브 위젯 세션	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
APIs	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Capability	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
원본 widget 메시지	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

원본

플러그인 저장소에서 전체 타입 참조가 있습니다. src/definitions.ts.