시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

가져오기

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

빠른 시작

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

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

예시: startTemplateActivity

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

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

예시: startTemplateWidget

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

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

자주 하는 실수

• 네이티브 동기화: 실행 bunx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

iOS 설정

Live Activities 및 WidgetKit 확장을 사용하려면 먼저 네이티브 앱을 설정해야 합니다:

• 가능한 경우 대화형 Live Activity 버튼을 위해 iOS 17 이상 버전을 사용하세요.
• 추가 NSSupportsLiveActivities 앱에 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 템플릿 Activity

위젯이 렌더링된 SVG를 표시할 수 있는 경우 이 모드를 사용하세요. 플러그인이 상태를 저장하고, 플레이스홀더를 해석하며, 탭 액션을 적용하고, 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,
});

iOS에서 위젯 확장 버튼은 번들된 LiveActivityIntent 헬퍼를 (CapgoTemplateActionIntent) 호출하여 동일한 이벤트 로그에 기록할 수 있습니다. 이는 Siri 단축어 문구나 Shortcuts 앱과는 별개입니다. 자세한 내용은 Siri, 단축어 및 위젯.

액티비티 업데이트 또는 종료

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

프레임 변이(Frame Mutations)

프레임 변이는 활성 프레임 ID를 상태에 기록합니다. 레이아웃은 다음을 통해 이를 읽을 수 있습니다: frameIdPath.

Operation	동작 방식
set	특정 프레임 ID 설정. 일반 문자열은 리터럴 프레임 ID로 처리되며, {{...}} 템플릿이 먼저 해석됩니다.
next	다음 프레임으로 이동 frameIds 또는 다음에 선언된 프레임 surface.
previous	이전 프레임으로 이동합니다.
toggle	사용 가능한 처음 두 프레임 사이를 전환하거나, 현재 프레임과 frameId.

mutation에 알려진 선택 가능한 프레임 목록이 있으면 잘못된 프레임 ID는 무시되므로, 상태는 렌더링된 화면과 계속 일치합니다.

타이머 Mutation

Timer mutation은 다음에서 이름이 지정된 타이머를 대상으로 합니다. definition.timers.

작업	동작 방식
start / restart	현재 지속 시간을 사용하여 0부터 시작합니다.
pause	경과 시간을 저장하고 초기화 startedAt.
resume	일시 정지된 타이머만 재개합니다. 중지된 타이머는 명시적인 시작 또는 재시작 전까지 중지 상태를 유지합니다.
toggle	실행 중인 타이머를 일시 중지하거나 일시 중지된 타이머를 재개합니다.
reset	경과 시간을 초기화하고 대기 상태로 돌아갑니다.
stop	실행 진행 상황을 초기화하고 타이머가 중지되었음을 표시합니다.
setDuration	지속 시간이 변경된 후 상태를 다시 계산합니다.

타이머 바인딩은 SVG에서 다음과 같이 사용할 수 있습니다: {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}및 관련 필드.

옵션 2: Full-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 },
});

작업을 실패시키려면 다음을 전달하세요: error 를 전달하고 response:

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

completeWidgetMessage 멱등성이 보장됩니다. 메시지가 이미 완료되었거나 실패한 경우, 반복 호출 시 기존 메시지 스냅샷을 반환합니다.

Native Session 중지

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

API 그룹

그룹	API
기능	areActivitiesSupported, getPluginVersion
SVG 액티비티 생명주기	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG 액션 및 이벤트	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
네이티브 위젯 세션	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
네이티브 위젯 메시지	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Source of Truth

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

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-widget-kit 사용하기 @capgo/capacitor-widget-kit를 사용하여 네이티브 기능을 구현할 때, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.