위젯 키트 __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.

만들기 옵션을 선호하시면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르십시오.

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 템플릿 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 Mutation

Frame mutations는 현재 프레임 ID를 상태에 기록합니다. 레이아웃은 이를 읽을 수 있습니다. frameIdPath.

작업	행동
set	특정 프레임 ID를 설정합니다. 단순 문자열은 Literal 프레임 ID로 처리되며, 템플릿은 먼저 해독됩니다. {{...}} 다음 프레임으로 이동
next	또는 선언된 프레임 frameIds 이전 프레임으로 이동 surface.
previous	현재 프레임과 첫 번째 두 개의 사용 가능한 프레임 사이를 토글합니다.
toggle	알맞은 프레임 목록이 있는 변형이 알려진 경우, 무효한 프레임 ID는 무시되며 상태는 렌더링된 표면과 동기화됩니다. frameId.

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__ definition.timers.

__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
start / restart	__CAPGO_KEEP_0__
pause	__CAPGO_KEEP_0__ startedAt.
resume	__CAPGO_KEEP_0__
toggle	__CAPGO_KEEP_0__
reset	__CAPGO_KEEP_0__
stop	__CAPGO_KEEP_0__
setDuration	__CAPGO_KEEP_0__

타이머 바인딩은 SVG에 사용할 수 있습니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}그리고 관련 필드.

옵션 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 이 메시지는 idempotent입니다. 메시지가 이미 완료되거나 실패한 경우, 반복 호출은 기존 메시지 스냅샷을 반환합니다.

자연스션 중지

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

API 그룹

API	능력
SVG 활동 생명주기	areActivitiesSupported, getPluginVersion
SVG 액션 및 이벤트	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Copy to clipboard	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
자연스러운 위젯 세션	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
자연스러운 위젯 메시지	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

실제 데이터 원천

플러그인 저장소에서 전체 타입 참조가 있습니다. src/definitions.ts.

Getting Started에서 계속

Getting Started을 사용하여 Getting Started을 사용하여 Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Using @capgo/capacitor-widget-kit 자연스러운 위젯 키트를 사용하여 @capgo/capacitor Capgo 플러그인 디렉토리 Capgo 제품 워크플로우를 위한 Capgo 플러그인 디렉토리 Capacitor Capgo 플러그인 Capgo 제품 워크플로우를 위한 Capacitor Capgo 플러그인 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 세부 정보를 위한, 아이오닉 엔터프라이즈 플러그인 대체 Capgo 제품 워크플로우를 위한 아이오닉 엔터프라이즈 플러그인 대체