위젯 키트 __CAPGO_KEEP_0__ 저장소

설치하기

Capgo의 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 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);
}

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

위젯 이벤트 처리

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

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를 설정합니다. 단순 문자열은 프레임 id로 처리되며, 템플릿은 먼저 해독됩니다. {{...}} 다음 프레임으로 이동
next	또는 선언된 프레임 frameIds 이전 프레임으로 이동 surface.
previous	현재 프레임과 첫 번째 두 개의 프레임 또는 현재 프레임과 두 번째 프레임 사이를 토글합니다.
toggle	__CAPGO_KEEP_0__ frameId.

알 수 없는 프레임 아이디는 선택 가능한 프레임 목록이 있는 변형이 알려진 경우 무시되며, 상태는 렌더링된 표면과 동기화된다.

타이머 변형

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

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

SVG에서 타이머 바인딩은 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, 관련 필드도 있습니다.

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

작업을 실패시키려면 error 대신 response:

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

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

자연스션 중지

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.

Getting Started

Getting Started Capgo 위젯 키트를 사용하여 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__을 연결합니다. Getting Started Using @capgo/capacitor-widget-kit Capgo의 원시 기능을 사용하는 @capgo/capacitor-widget-kit 에 대해 Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우에 대해 Capacitor 플러그인에 의해 Capgo Capacitor 플러그인에 의해 Capgo의 구현 세부 정보에 대해 플러그인을 추가하거나 업데이트하는 것 플러그인을 추가하거나 업데이트하는 것의 구현 세부 정보, 그리고 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안의 제품 워크플로우에 대해