Getting Started

설치

플러그인을 설치하기 위해 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

__CAPGO_KEEP_0__

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

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__

• __CAPGO_KEEP_4__
• __CAPGO_KEEP_5__ NSSupportsLiveActivities __CAPGO_KEEP_6__ Info.plist __CAPGO_KEEP_7__
• __CAPGO_KEEP_8__
• 설정 CapgoWidgetKitAppGroup 파일을 공유된 App Group 식별자에 두세요. 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);
}

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

Run Actions From The App

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

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

프레임 변형

Frame mutations __CAPGO_KEEP_0__ state에 현재 프레임 id를 기록합니다. 레이아웃은 그 후에 이를 읽을 수 있습니다. frameIdPath.

Operation	Behavior
set	특정 프레임 id를 설정합니다. 평범한 문자열은 literal 프레임 id로 처리되며, 템플릿은 먼저 해독됩니다. {{...}} 다음 프레임으로 이동하십시오.
next	또는 선언된 프레임 목록에서 frameIds 이전 프레임으로 이동하십시오. surface.
previous	현재 프레임과 첫 번째 두 개의 프레임 사이를 전환하십시오.
toggle	알맞지 않은 프레임 id는 선택 가능한 프레임 목록이 알려진 경우 mutation이 렌더링된 표면과 일치하는 상태를 유지하기 위해 무시됩니다. frameId.

타이머 변형

타이머 변형

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

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

SVG와 관련된 field와 함께 타이머 바인딩이 사용 가능합니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}__CAPGO_KEEP_0__

Option 2: Full-Native Widget Session

이 모드는 위젯 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);

Async Widget Messages

위젯이 앱으로부터 데이터를 동기화하도록 요청하는 등 후속 응답이 필요한 작업을 처리하는 메시지는 모두 포함됩니다.

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

To fail the job, pass error 대신 response:

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

completeWidgetMessage is idempotent. If the message is already completed or failed, repeated calls return the existing message snapshot.

__CAPGO_KEEP_0__ 세션 중지

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.

시작부터 계속

Capacitor를 사용하는 경우 시작 Capacitor를 사용하여 네이티브 플러그인 작업을 계획할 때, Capacitor를 사용하여 네이티브 기능을 사용하는 @capgo/capacitor-widget-kit Capacitor를 사용하여 @capgo/capacitor-widget-kit의 네이티브 기능 Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 정보를 위해 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 정보를 위해, 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체의 제품 워크플로에 대해