Widget Kit __CAPGO_KEEP_0__ 저장소

설치

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

Frame Mutations

액티브 프레임 ID를 상태에 기록합니다. 레이아웃은 이를 읽을 수 있습니다. frameIdPath.

Operation	Behavior
set	특정 프레임 ID를 설정합니다. 단순 문자열은 프레임 ID로 처리되며 템플릿은 먼저 해독됩니다. {{...}} 다음 프레임으로 이동
next	또는 선언된 프레임 frameIds 이전 프레임으로 이동 surface.
previous	현재 프레임과 첫 번째 두 개의 프레임 사이를 토글합니다.
toggle	templates are resolved first. frameId.

잘못된 프레임 아이디는 알려진 선택 가능한 프레임 목록이 있는 변형이 있는 경우 무시되므로 상태는 렌더링된 표면과 일치합니다.

타이머 변형

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

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

SVG에서 타이머 바인딩은 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, 관련 field.

Option 2: 풀 네이티브 위젯 세션

위젯 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 중복 호출은 이미 완료되거나 실패한 메시지의 스냅샷을 반환합니다.

자연 세션 중지

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

API 그룹

API	능력
SVG 활동 생명주기	areActivitiesSupported, getPluginVersion
__CAPGO_KEEP_0__ 그룹	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에서 계속하기

Capgo를 사용하여 네이티브 플러그인 작업을 계획하고 있습니다. Capgo를 사용하여 네이티브 플러그인 작업을 계획하고 있습니다. Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Using @capgo/capacitor-widget-kit Capgo의 원시 기능을 사용하는 @capgo/capacitor-widget-kit 에 대해 Capgo 플러그인 디렉토리 Capgo의 제품 워크플로우에 대해 Capgo 플러그인 디렉토리 에 대해 Capacitor 플러그인들에 대해 Capgo Capgo의 구현 세부 정보에 대해 Capacitor 플러그인들에 대해 Capgo 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 에서의 구현 세부 정보, 그리고 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안 에서의 제품 워크플로우