スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

bunx 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 { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

クイックスタート

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

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

例: startTemplateActivity

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

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

例: startTemplateWidget

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

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

よくある落とし穴

• ネイティブ同期: 実行 bunx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼 src/definitions.ts GitHub リポジトリ内。

iOSのセットアップ

Live ActivitiesおよびWidgetKit拡張機能を使用するには、まずネイティブアプリの設定を行ってください：

• 可能な限り、インタラクティブなLive Activityボタンを利用するために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);
}

オプション1: SVG Template Activity

ウィジェットが解決済みのSVGをレンダリングできる場合は、このモードを使用してください。このプラグインは、状態の保存、プレースホルダーの解決、タップアクションの適用、SVGフレームの切り替え、およびタイマー状態の一貫性を維持します。

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

Widgetのイベントを処理する

アクションはイベントを発行するので、アプリは起動後や復帰後にウィジェットのインタラクションを処理できます：

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

iOSでは、ウィジェット拡張機能のボタンから、同梱された LiveActivityIntent ヘルパー（CapgoTemplateActionIntent）を呼び出して、同じイベントログに書き込むことができます。これはSiriショートカットのフレーズやショートカットアプリとは別物です。詳細は Siri、ショートカット、ウィジェット.

Activityの更新または終了

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の変更

Frame mutationsは、アクティブなframe idをstateに書き込みます。これにより、layoutから以下の方法で読み取ることが可能です： frameIdPath.

Operation	動作
set	特定のframe idを設定します。プレーンな文字列はリテラルなframe idとして扱われ、 {{...}} テンプレートは先に解決されます。
next	次のframeへ移動： frameIds または、以下で宣言されたフレーム: surface.
previous	前のフレームに移動します。
toggle	利用可能な最初の2つのフレーム間、または現在のフレームと以下を切り替えます: frameId.

ミューテーション時に選択可能なフレームリストが判明している場合、無効なフレームIDは無視されるため、状態はレンダリングされたサーフェスと同期したままになります。

Timerの変更

Timer mutationsは、以下から指定されたタイマーを対象にします: definition.timers.

操作	動作
start / restart	現在の継続時間を使用してゼロから開始します。
pause	経過時間を保存し、以下をクリアします: startedAt.
resume	一時停止中のタイマーのみ再開します。停止中のタイマーは、明示的な開始または再起動が行われるまで停止したままになります。
toggle	実行中のタイマーを一時停止、または一時停止中のタイマーを再開します。
reset	経過時間をリセットしてアイドル状態に戻します。
stop	実行中の進捗をクリアし、タイマーを停止状態にします。
setDuration	期間の変更後にステータスを再計算します。

タイマーのバインディングは SVG で次のように利用できます: {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}、および関連するフィールド。

オプション 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 メッセージ

メッセージは、データの同期をアプリに要求するウィジェットなど、後で対応が必要なタスクを扱います。

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 は冪等（べきとう）です。メッセージが既に完了または失敗している場合、繰り返し呼び出しても既存のメッセージのスナップショットが返されます。

Native Sessionを停止する

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の続きを進める

使用している場合 スタートガイド ネイティブプラグインの作業を計画するには、次と連携してください： @capgo/capacitor-widget-kit の使用 「@capgo/capacitor-widget-kit の使用」のネイティブ機能については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 プラグインの追加または更新 プラグインの追加または更新における実装詳細については、および Ionic Enterprise プラグインの代替案 Ionic Enterprise プラグインの代替案におけるプロダクトワークフローについては。