Getting Started

설치

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>

__CAPGO_KEEP_1__

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

__CAPGO_KEEP_3__

__CAPGO_KEEP_5__

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

__CAPGO_KEEP_6__

__CAPGO_KEEP_0__

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

프레임 변형

작업 frameIdPath.

행동	프레임 변형
set	__CAPGO_KEEP_0__을 지정합니다. 단순 문자열은 __CAPGO_KEEP_0__을 literal frame id로 처리합니다; {{...}} 템플릿은 먼저 해결됩니다.
next	__CAPGO_KEEP_0__으로부터 다음 프레임으로 이동합니다. frameIds 또는 __CAPGO_KEEP_0__에 선언된 프레임들 중에서 surface.
previous	__CAPGO_KEEP_0__으로부터 이전 프레임으로 이동합니다.
toggle	__CAPGO_KEEP_0__과 __CAPGO_KEEP_0__ 사이를 토글합니다. 또는 현재 프레임과 __CAPGO_KEEP_0__ 사이를 토글합니다. frameId.

__CAPGO_KEEP_0__ id가 유효하지 않으면, mutation이 알려진 선택 가능한 프레임 목록을 가지고 있다면, state는 렌더링된 표면과 동기화가 유지됩니다.

타이머 변형

타이머 변형은 __CAPGO_KEEP_0__ 이름을 가진 타이머를 대상으로 합니다. definition.timers.

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

SVG와 관련된 field에서 타이머 바인딩이 사용 가능합니다. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}Option 2: 풀 네이티브 위젯 세션

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

네이티브 세션 중지

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.

Getting Started에서 계속 진행하세요

Capgo를 사용 중이라면 Getting Started native 플러그인 작업을 계획하고자 할 때, Using @capgo/capacitor-widget-kit for the native capability in Using @capgo/capacitor-widget-kit, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Capgo 플러그인 디렉토리에서 Capgo 플러그인 디렉토리와의 연관성을 이해하는 방법 __CAPGO_KEEP_0__ 구현 세부 사항에 대한 정보는 Adding or Updating Plugins 항목에서 제공됩니다. Ionic Enterprise Plugin Alternatives __CAPGO_KEEP_0__ 제품 워크플로우에 대한 정보는 Ionic Enterprise Plugin Alternatives 항목에서 제공됩니다.