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	__CAPGO_KEEP_0__ frameId.

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

타이머 변형

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

작업	동작
start / restart	현재 지속 시간을 기준으로 0부터 시작합니다.
pause	누적 시간을 저장하고 startedAt.
resume	일시 정지된 타이머만 재개합니다. 중단된 타이머는 명시적 시작 또는 재시작을 기다립니다.
toggle	일시 정지된 타이머를 일시 정지하거나 일시 정지된 타이머를 재개합니다.
reset	누적 시간을 지우고
stop	일시 정지된 타이머를 중단하고
setDuration	__CAPGO_KEEP_0__

Timer SVG 바인딩 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}SVG 및 관련 field

2. 원본 Widget 세션

이 모드는 widget UI가 원본 code에서 빌드되었을 때 사용합니다. 플러그인은 앱과 widget에 공유된 세션 레코드와 메시지 큐를 제공합니다.

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

비동기 Widget 메시지

메시지는 응답이 필요하지만 나중에 이루어지는 작업을 다룹니다. 예를 들어, widget가 앱에 데이터를 동기화하도록 요청하는 경우입니다.

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 Capacitor와 함께 사용하여 네이티브 위젯 키트를 연결합니다. @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit @capgo/capacitor-widget-kit Capgo의 내장 기능을 사용하는 @capgo/capacitor-widget-kit에 대해 Capgo 플러그인 디렉토리 Capgo의 제품 워크플로우에 대해 Capgo 플러그인 디렉토리 Capacitor 플러그인들 - Capgo Capgo의 구현 세부 정보에 대해 Capacitor 플러그인들 - Capgo 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에 대한 구현 세부 정보, 그리고 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체에 대한 제품 워크플로우