시작하기

설치

플러그인을 설치하기 위해 AI-Assisted Setup을 사용할 수 있습니다. 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>

지원 확인

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

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

Option 1: SVG 템플릿 액티비티

이 모드는 위젯이 해결된 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',
});

위젯 이벤트 처리

액션은 런치 또는 재개 후 위젯 상호 작용을 처리하기 위해 앱이 이벤트를 처리할 수 있도록 합니다:

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	__CAPGO_KEEP_0__
toggle	첫 번째 두 개의 사용 가능한 프레임 사이를 토글하거나, 현재 프레임과 frameId.

알맞은 프레임 목록이 있는 변형이 알려진 선택 가능한 프레임 목록을 가지고 있으면, 무효 프레임 id는 무시되므로 렌더링된 표면과 상태가 동기화된다.

타이머 변형

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

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

SVG에서 타이머 바인딩이 사용 가능합니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, 및 관련 field.

2. 풀 네이티브 위젯 세션

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

동기식 위젯 메시지

메시지는 앱이 데이터를 동기화할 것을 요청하는 등 후속 응답이 필요한 작업을 처리합니다.

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_0__ 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

진실의 근원

플러그인 저장소에 있는 전체 타입 참조는 다음 위치에 있습니다. src/definitions.ts.

Getting Started에서 계속 진행하세요

Capgo를 사용하여 네이티브 플러그인 작업을 계획하고 있습니다. 시작하기 Capgo를 사용하여 네이티브 플러그인 작업을 계획하고 있습니다. Using @capgo/capacitor-widget-kit Capgo native 기능을 사용하는 @capgo/capacitor-widget-kit에 대해 Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리를 사용하여 Capacitor Plugins by Capgo Capacitor 플러그인 구현 세부 사항을 위해 Capgo에 의해 제공됩니다. 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안