Skip to content
Capgo - Live Updates for Capacitor Apps Capgo

Getting Started

  1. Install the plugin

    Terminal window
    npm i @capgo/capacitor-widget-kit

  2. Sync native platforms

    Terminal window
    npx cap sync

  3. Create and configure the widget extension

    • Add the same App Group to the main app target and the widget extension target.
    • Set CapgoWidgetKitAppGroup in both Info.plist files to that shared App Group identifier.

Platform requirements

Section titled “Platform requirements”
  • iOS 17 or later is recommended for the interactive completion button flow.
  • Add NSSupportsLiveActivities to the app Info.plist.
  • WidgetKit support is iOS-only. The web implementation is only for development previews.

Example App Group configuration:

<key>CapgoWidgetKitAppGroup</key>
<string>group.com.example.app.widgetkit</string>

Register the widget bundle

Section titled “Register the widget bundle”

Inside the widget extension, import the plugin package and expose your bundle:

import ActivityKit
import SwiftUI
import WidgetKit
import CapgoWidgetKitPlugin


@main
struct ExampleWidgetBundle: WidgetBundle {
    var body: some Widget {
        if #available(iOS 16.2, *) {
            ExampleTemplateLiveActivityWidget()
        }
    }
}

Start a template activity

Section titled “Start a template activity”
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';


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


if (!supported) {
  console.warn(reason);
}


const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  openUrl: 'widgetkitdemo://session/session-1',
  state: {
    title: 'Chest Day',
    count: 0,
    restDurationMs: 90000,
  },
  definition: {
    id: 'generic-session-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'complete-set',
        eventName: 'workout.set.completed',
        patches: [{ op: 'increment', path: 'count', amount: 1 }],
      },
    ],
    layouts: {
      lockScreen: {
        width: 100,
        height: 40,
        svg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 40">
  <rect x="0" y="0" width="100" height="40" rx="6" fill="#05070b" />
  <text x="6" y="10" fill="#ffffff">{{state.title}}</text>
  <text x="6" y="30" fill="#00d69c">{{timers.rest.remainingText}}</text>
</svg>`,
      },
    },
  },
});


console.log(activity.activityId);

Perform an action and read events

Section titled “Perform an action and read events”
await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'complete-set',
  sourceId: 'app-complete-set-button',
});


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


console.log(pendingEvents.events);
Section titled “Recommended usage”
  • Treat the shipped workout flow as an example, not the core abstraction.
  • Keep the widget extension responsible for rendering and let the Capacitor app own activity state and event processing.
  • Model actions declaratively so app-side buttons and widget hotspots can reuse the same behavior.