시작하기

설치

bun add @capgo/capacitor-widget-kit
bunx cap sync

import

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

iOS 설정

라이브 활동 및 위젯 키트 확장에 사용하려면 네이티브 앱을 먼저 구성하세요.

• iOS 17 이상을 사용하여 가능할 때 반응형 라이브 활동 버튼을 사용하세요.
• 추가 NSSupportsLiveActivities 앱 Info.plist 라이브 활동 키트를 사용할 때
• 위젯 확장 대상과 앱 대상에 동일한 앱 그룹을 추가하세요.
• 설정 CapgoWidgetKitAppGroup 파일 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 템플릿 활동을 사용할 때

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_2__

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

__CAPGO_KEEP_4__

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

__CAPGO_KEEP_7__

__CAPGO_KEEP_9__ frameIdPath.

__CAPGO_KEEP_10__	__CAPGO_KEEP_11__
set	특정 프레임 아이디를 설정합니다. 평범한 문자열은 Literal 프레임 아이디로 처리되며, 템플릿은 먼저 해결됩니다. {{...}} 템플릿은 먼저 해결됩니다.
next	다음 프레임으로 이동합니다. frameIds 또는 선언된 프레임 surface.
previous	이전 프레임으로 이동합니다.
toggle	첫 번째 두 개의 사용 가능한 프레임 사이를 전환하거나, 현재 프레임과 frameId.

알려진 선택 가능한 프레임 목록이 있는 변형이 알려진 프레임 아이디를 무시할 때, 렌더링된 표면과 상태가 동기화됩니다.

타이머 변형

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

작업	동작
start / restart	0에서 시작하기 위해 현재 지속 시간을 사용하세요.
pause	지남 시간을 저장하고 지우세요. startedAt.
resume	일시 정지된 타이머만 재개합니다. 중단된 타이머는 명시적 시작 또는 재시작을 기다려야 합니다.
toggle	실행 중인 타이머를 일시 정지하거나 일시 정지된 타이머를 재개하세요.
reset	지남 시간을 지우고 대기 상태로 돌아가세요.
stop	런타임 진행을 지우고 타이머를 중단 표시하세요.
setDuration	지속 시간 변경 후 상태를 재계산하세요.

타이머 바인딩은 SVG, , 및 관련 field에 사용할 수 있습니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}2. 옵션: 풀 네이티브 위젯 세션

제목: 2. 옵션: 풀 네이티브 위젯 세션

Timer bindings are available to SVG as code and related fields.

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
능력	areActivitiesSupported, getPluginVersion
SVG 활동 생명 주기	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG 액션 및 이벤트	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
자연어 위젯 세션	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
자연어 위젯 메시지	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

진실의 근원

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