Getting Started

설치

Capgo를 사용하여 AI 도구에 Capgo 스킬을 추가할 수 있습니다. 다음 명령어를 사용하세요:

npx 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.

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

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

Import

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

iOS 설정

라이브 활동 및 위젯 키트 확장에 대한 설정은 네이티브 앱을 먼저 구성해야 합니다:

• 가능한 경우, 인터랙티브 라이브 활동 버튼을 사용하기 위해 iOS 17+를 사용하세요.
• 활성 활동에 사용할 때 NSSupportsLiveActivities 앱 Info.plist 위젯 확장
• 위젯 확장과 앱 대상에 동일한 앱 그룹을 추가하세요.
• 위젯 확장 대상과 앱 대상의 CapgoWidgetKitAppGroup 파일에 공유 앱 그룹 식별자를 설정하세요. Info.plist 클립보드에 복사

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

Check Support

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

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

Option 1: SVG Template Activity

SVG를 렌더링할 수 있는 위젯이 있는 경우 이 모드를 사용하세요. 플러그인은 상태를 저장하고, 플레이스 홀더를 해결하고, 탭 액션을 적용하고, SVG 프레임을-switch하고, 타이머 상태를 일관되게 유지합니다.

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

위젯 이벤트 처리

__CAPGO_KEEP_0__이벤트를 발생시켜 앱이 런치나 재개 후 위젯 상호작용을 처리할 수 있도록 합니다.

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

__CAPGO_KEEP_2__활동을 업데이트 또는 종료하세요.

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

__CAPGO_KEEP_4__프레임 변형

__CAPGO_KEEP_6__프레임 변형은 현재 프레임 id를 상태에 기록합니다. 레이아웃은 이를 읽을 수 있습니다. frameIdPath.

__CAPGO_KEEP_7__작업	__CAPGO_KEEP_8__동작
set	__CAPGO_KEEP_9__특정 프레임 id를 설정하세요. 단순 문자열은 리터럴 프레임 id로 처리되며 템플릿은 우선적으로 해결됩니다. {{...}} __CAPGO_KEEP_10__템플릿
next	다음 프레임으로 이동하세요. frameIds or 선언된 프레임들 surface.
previous	이전 프레임으로 이동하세요.
toggle	첫 번째 두 개의 사용 가능한 프레임 사이를 토글하거나, 현재 프레임과 사이를 토글하세요. frameId.

알려진 선택 가능한 프레임 목록이 있는 변형이 렌더링 된 표면과 일치하는 상태를 유지하기 위해 무효 프레임 id는 변형 시 무시됩니다.

타이머 변형

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

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

SVG와 관련된 field에서 타이머 바인딩이 사용 가능합니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}Option 2: 풀 네이티브 위젯 세션

네이티브 __CAPGO_KEEP_0__ 위젯 UI가 빌드된 경우 이 모드를 사용하세요. 플러그인은 앱과 위젯에 공유된 세션 기록과 메시지 큐를 제공합니다.

Use this mode when the widget UI is built in native code. The plugin gives the app and widget a shared session record and a message queue.

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

Copy to clipboard

메시지는 데이터를 동기화하도록 앱에 요청하는 위젯과 같은 후속 응답이 필요한 작업을 다룹니다.

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 이 메시지는 이미 완료되거나 실패한 경우, 동일한 메시지 스냅샷을 반환합니다.

자연스스 세션 중지

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

진실의 근원

The full type reference lives in the plugin repository at src/definitions.ts.

Getting Started에서 계속

If you are using __CAPGO_KEEP_0__ Getting Started native 앱 개발을 위해 __CAPGO_KEEP_0__을 연결하세요. capgo을 사용하여 capacitor-widget-kit을 사용하세요. for the native capability in Using @capgo/capacitor-widget-kit, Capgo Plugin Directory Capgo Plugin Directory에서 제품 워크플로우를 사용하세요. Capacitor Plugins by Capgo Capacitor Plugins by Capgo에서 구현 세부 정보를 확인하세요. Adding or Updating Plugins Adding or Updating Plugins에서 구현 세부 정보를 확인하세요. Ionic Enterprise Plugin Alternatives __CAPGO_KEEP_0__