@capgo/capacitor-widget-kitを使用すると、capgoアプリは、2つの方法でウィジェットキットとライブアクティビティのエクスペリエンスを制御できます。

@capgo/capacitor-widget-kit Capacitorアプリがウィジェットキットとライブアクティビティのエクスペリエンスを制御する2つの方法を提供します。

解決されたSVGテンプレート表面をフレーム切り替え、タップホットスポット、タイマー停止/再生とともにレンダリングします。
アプリとウィジェットはJSONセッション状態と非同期メッセージを共有しながら、ウィジェットを完全にネイティブに維持します。

インストール

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

SVGテンプレートを使用するタイミング

ウィジェット表面がSVGで表現できる場合、SVGテンプレートを使用します。アプリはテンプレート定義を保存し、ネイティブブリッジはプレースホルダーを解決し、ウィジェットのタップは後で状態を変化させることができます。

適切な例には、トレーニングタイマー、配達状況カード、スポーツスコア、またはコンパクトなUIで名前付きフレーム間の切り替えが十分なものがあります。

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

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
      },
      {
        id: 'toggle-rest',
        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>`,
          },
        ],
      },
    },
  },
});

アプリ内でウィジェットのアクションを処理する

ウィジェットのアクションはイベントとして保存されます。アプリが再開したときやバックグラウンドの同期ステップ後に、読み取りおよび確認してください。

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log(event.actionId, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({ activityId: activity.activityId });

フルネイティブセッションを使用するときの適切なシナリオ

Use full-native sessions when the widget UI is better built directly in Swift, Kotlin, or Java. Capacitor still starts and stops the session, keeps shared state current, and queues work between app and widget 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 { 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 },
});

ジョブが失敗した場合、エラーを含めてメッセージを完了してください。

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

セッションを適切に終了する

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

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

ネイティブセットアップの注意点

iOS WidgetKitおよびLive Activitiesの場合、アプリとウィジェット拡張ターゲットにアプリグループを設定し、両方のファイルに設定してください。 CapgoWidgetKitAppGroup 両方の Info.plist ファイル

フルリファレンス

GitHub: https://github.com/Cap-go/capacitor-widget-kit/
ドキュメント: /docs/plugins/widget-kit/

ウィジェットキット