@capgo/capacitor-widget-kit

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Create WidgetKit, ActivityKit, and Android widget experiences from Capacitor without forcing one rendering model.

The plugin has two implementation paths:

SVG template activities: store SVG layouts, optional named frames, hotspots, declarative state patches, pause/resume timers, and interaction events. Use this when your widget can be driven by resolved SVG output.
Full-native widget sessions: store shared JSON state for native widget code and queue app-to-widget or widget-to-app messages. Use this when you want to render the widget fully in Swift/Kotlin/Java but still need Capacitor to start, stop, sync, or process async work.

The included workout flow is only an example helper built on top of the generic SVG abstraction.

Install

bun add file:../capacitor-widget-kit
bunx cap sync ios
bunx cap sync android

iOS Requirements

iOS 17+ is recommended for interactive Live Activity buttons.
Add NSSupportsLiveActivities to the app Info.plist when using ActivityKit.
Add the same App Group to the app target and the widget extension target.
Set CapgoWidgetKitAppGroup in both Info.plist files to the shared App Group identifier.

Example App Group:

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Native Widget Code

The plugin ships the native pieces a widget extension or Android widget can use:

CapgoTemplateActivityAttributes for the iOS Live Activity bridge
CapgoTemplateActionIntent for interactive iOS template buttons
CapgoTemplateWidgetBridge to load a stored SVG activity and resolve one surface into svg + width/height + frameId + hotspots + metadata
CapgoNativeWidgetBridge to load full-native widget sessions and exchange async messages without using SVG templates
CapgoTemplateActionReceiver and CapgoTemplateWidgetBridge for Android template widgets

In your iOS widget extension bundle:

import ActivityKit
import SwiftUI
import WidgetKit
import CapgoWidgetKitPlugin

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

See example-app/widget-extension/ExampleWidgetBundle.swift for a complete scaffold. The sample intentionally uses a placeholder card so you can plug in your own SVG renderer while keeping the same bridge and action intent wiring.

SVG Template Usage

This mode is for widgets that can render resolved SVG. Hotspot actions can switch frames, mutate state, pause/play timers, and emit events for the app to process later.

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

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  openUrl: 'widgetkitdemo://session/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'generic-session-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="20">{{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="20">{{timers.rest.remainingText}}</text></svg>`,
          },
        ],
      },
    },
  },
});

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

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

Full-Native Widget Usage

This mode is for widgets rendered in native code. The app keeps a shared session state for sync reads/writes, and messages cover async jobs that need a later response.

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.completeWidgetMessage({
  messageId: message.messageId,
  response: { synced: true },
});

await CapgoWidgetKit.stopWidgetSession({ widgetId: session.widgetId });

Example App

The example-app/ folder is a lightweight Vite demo for the generic template flow. It runs in the browser using the preview store and demonstrates:

starting one SVG template activity
resolving the lock-screen surface
running an action from the app and from a hotspot overlay
reading the stored activity back
reading and acknowledging the event log
ending the activity

The workout helper is only used there as an example template factory.

API

areActivitiesSupported()
startTemplateActivity(...)
updateTemplateActivity(...)
endTemplateActivity(...)
performTemplateAction(...)
getTemplateActivity(...)
listTemplateActivities()
listTemplateEvents(...)
acknowledgeTemplateEvents(...)
startWidgetSession(...)
updateWidgetSession(...)
stopWidgetSession(...)
getWidgetSession(...)
listWidgetSessions()
sendWidgetMessage(...)
listWidgetMessages(...)
acknowledgeWidgetMessages(...)
completeWidgetMessage(...)
getPluginVersion()
Interfaces
Type Aliases

Capacitor bridge for an iOS-first WidgetKit / Live Activities plugin.

The core abstraction is a generic SVG template activity:

raw SVG templates with binding placeholders
declarative action patches
timer bindings exposed to the template scope
event logging so the host app can process button results later

The plugin owns shared persistence, declarative action execution, and event retrieval. The host widget extension keeps full freedom over actual WidgetKit rendering.

Full-native widgets can use widget sessions for synchronous shared state and widget messages for asynchronous app/widget jobs without adopting the SVG template renderer.

areActivitiesSupported()

areActivitiesSupported() => Promise<ActivitiesSupportedResult>

Check whether the native template activity bridge can run on the current device.

Returns: Promise<ActivitiesSupportedResult>

startTemplateActivity(...)

startTemplateActivity(options: StartTemplateActivityOptions) => Promise<StartTemplateActivityResult>

Persist a generic SVG template activity and start the matching native Live Activity bridge.

Param	Type
`options`	`StartTemplateActivityOptions`

Returns: Promise<StartTemplateActivityResult>

updateTemplateActivity(...)

updateTemplateActivity(options: UpdateTemplateActivityOptions) => Promise<TemplateActivityResult>

Replace part or all of the stored activity definition/state.

Param	Type
`options`	`UpdateTemplateActivityOptions`

Returns: Promise<TemplateActivityResult>

endTemplateActivity(...)

endTemplateActivity(options: EndTemplateActivityOptions) => Promise<void>

End a running activity while optionally persisting one last state snapshot.

Param	Type
`options`	`EndTemplateActivityOptions`

performTemplateAction(...)

performTemplateAction(options: PerformTemplateActionOptions) => Promise<PerformTemplateActionResult>

Execute one declarative action and record the resulting event.

Param	Type
`options`	`PerformTemplateActionOptions`

Returns: Promise<PerformTemplateActionResult>

getTemplateActivity(...)

getTemplateActivity(options: GetTemplateActivityOptions) => Promise<TemplateActivityResult>

Read one activity back from the shared store.

Param	Type
`options`	`GetTemplateActivityOptions`

Returns: Promise<TemplateActivityResult>

listTemplateActivities()

listTemplateActivities() => Promise<ListTemplateActivitiesResult>

List every activity currently known by the plugin.

Returns: Promise<ListTemplateActivitiesResult>

listTemplateEvents(...)

listTemplateEvents(options?: ListTemplateEventsOptions | undefined) => Promise<ListTemplateEventsResult>

List stored action events so the app can react to widget interactions later.

Param	Type
`options`	`ListTemplateEventsOptions`

Returns: Promise<ListTemplateEventsResult>

acknowledgeTemplateEvents(...)

acknowledgeTemplateEvents(options: AcknowledgeTemplateEventsOptions) => Promise<void>

Mark previously processed events as acknowledged.

Param	Type
`options`	`AcknowledgeTemplateEventsOptions`

startWidgetSession(...)

startWidgetSession(options: StartWidgetSessionOptions) => Promise<StartWidgetSessionResult>

Start a full-native widget session backed by shared JSON state.

Param	Type
`options`	`StartWidgetSessionOptions`

Returns: Promise<StartWidgetSessionResult>

updateWidgetSession(...)

updateWidgetSession(options: UpdateWidgetSessionOptions) => Promise<WidgetSessionResult>

Update a full-native widget session.

Param	Type
`options`	`UpdateWidgetSessionOptions`

Returns: Promise<WidgetSessionResult>

stopWidgetSession(...)

stopWidgetSession(options: StopWidgetSessionOptions) => Promise<void>

Stop a full-native widget session.

Param	Type
`options`	`StopWidgetSessionOptions`

getWidgetSession(...)

getWidgetSession(options: GetWidgetSessionOptions) => Promise<WidgetSessionResult>

Read one full-native widget session.

Param	Type
`options`	`GetWidgetSessionOptions`

Returns: Promise<WidgetSessionResult>

listWidgetSessions()

listWidgetSessions() => Promise<ListWidgetSessionsResult>

List every full-native widget session currently known by the plugin.

Returns: Promise<ListWidgetSessionsResult>

sendWidgetMessage(...)

sendWidgetMessage(options: SendWidgetMessageOptions) => Promise<SendWidgetMessageResult>

Queue a message between the app and native widget code.

Param	Type
`options`	`SendWidgetMessageOptions`

Returns: Promise<SendWidgetMessageResult>

listWidgetMessages(...)

listWidgetMessages(options?: ListWidgetMessagesOptions | undefined) => Promise<ListWidgetMessagesResult>

List queued full-native widget bridge messages.

Param	Type
`options`	`ListWidgetMessagesOptions`

Returns: Promise<ListWidgetMessagesResult>

acknowledgeWidgetMessages(...)

acknowledgeWidgetMessages(options: AcknowledgeWidgetMessagesOptions) => Promise<void>

Mark widget bridge messages as acknowledged after processing.

Param	Type
`options`	`AcknowledgeWidgetMessagesOptions`

completeWidgetMessage(...)

completeWidgetMessage(options: CompleteWidgetMessageOptions) => Promise<WidgetMessageResult>

Complete or fail an async widget bridge message.

Param	Type
`options`	`CompleteWidgetMessageOptions`

Returns: Promise<WidgetMessageResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Return the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

ActivitiesSupportedResult

Result of a Live Activities capability check.

Prop	Type	Description
`supported`	`boolean`	Whether the current device and runtime can run the native template activity bridge.
`reason`	`string`	Human-readable reason when support is unavailable.

StartTemplateActivityResult

Result when starting a generic template activity.

Prop	Type	Description
`activity`	`SvgTemplateActivityRecord`	Stored activity snapshot.

SvgTemplateActivityRecord

Stored activity snapshot returned by the plugin.

Prop	Type	Description
`activityId`	`string`	Stable plugin activity identifier.
`definition`	`SvgTemplateDefinition`	Full template definition.
`state`	`SvgTemplateState`	Persisted JSON state.
`timers`	`Record<string, SvgTemplateTimerState>`	Timer runtime state keyed by timer id.
`status`	`'active' \| 'ended'`	Current lifecycle status.
`openUrl`	`string`	Optional deep link opened when the widget body is tapped.
`updatedAt`	`number`	Last update timestamp.
`revision`	`number`	Monotonic revision incremented on every state change.

SvgTemplateDefinition

Generic SVG template definition stored by the plugin.

Prop	Type	Description
`id`	`string`	Stable template identifier.
`version`	`string`	Optional version marker for migrations.
`layouts`	`SvgTemplateLayouts`	Available WidgetKit layouts.
`actions`	`SvgTemplateActionDefinition[]`	Optional declarative actions.
`timers`	`SvgTemplateTimerDefinition[]`	Optional timer definitions exposed to the template runtime.
`metadata`	`JsonObject`	Optional JSON metadata mirrored in the runtime scope under `meta.template`.

SvgTemplateLayouts

Bundle of optional WidgetKit surface layouts.

Prop	Type	Description
`lockScreen`	`SvgTemplateLayout`	Primary lock-screen / banner layout.
`dynamicIslandExpanded`	`SvgTemplateLayout`	Optional expanded Dynamic Island layout.
`dynamicIslandCompactLeading`	`SvgTemplateLayout`	Optional compact leading Dynamic Island layout.
`dynamicIslandCompactTrailing`	`SvgTemplateLayout`	Optional compact trailing Dynamic Island layout.
`dynamicIslandMinimal`	`SvgTemplateLayout`	Optional minimal Dynamic Island layout.

SvgTemplateLayoutWithSvg

SVG layout variant backed by a base SVG string.

Prop	Type	Description
`svg`	`string`	Raw SVG template string used when no frame is selected. The runtime resolves `{{state.}}`, `{{timers.}}`, and `{{meta.*}}` placeholders before rendering.
`frames`	`SvgTemplateFrame[]`	Optional named SVG frames for click-driven or timer-driven frame changes.
`frameIdPath`	`string`	Optional state/runtime path that resolves to the active frame id. Examples: `state.frame`, `state.widgets.{{state.activeIndex}}.frame`, or `{{state.frame}}`.
`defaultFrameId`	`string`	Frame id used when `frameIdPath` is missing or resolves to an unknown frame.
`width`	`number`	Nominal SVG width used for scaling hotspots.
`height`	`number`	Nominal SVG height used for scaling hotspots.
`hotspots`	`SvgTemplateHotspot[]`	Interactive overlay regions.

SvgTemplateFrame

Named SVG frame that can be selected by activity state.

Prop	Type	Description
`id`	`string`	Stable frame identifier.
`svg`	`string`	Raw SVG template string for this frame. The runtime resolves `{{state.}}`, `{{timers.}}`, and `{{meta.*}}` placeholders before rendering.
`hotspots`	`SvgTemplateHotspot[]`	Optional frame-specific interactive regions. When omitted, the parent layout hotspots are used.

SvgTemplateHotspot

Interactive region overlaid on top of a rendered SVG layout.

Prop	Type	Description
`id`	`string`	Stable hotspot identifier.
`actionId`	`string`	Action identifier executed when the region is tapped.
`x`	`number`	X position in the SVG coordinate space.
`y`	`number`	Y position in the SVG coordinate space.
`width`	`number`	Hotspot width in the SVG coordinate space.
`height`	`number`	Hotspot height in the SVG coordinate space.
`label`	`string`	Optional accessibility label for the interactive region.
`role`	`'button' \| 'link'`	Optional semantic role.
`payload`	`JsonObject`	Optional static payload forwarded when the hotspot triggers its action.

JsonObject

JSON-safe object used as activity state.

SvgTemplateLayoutWithFrames

SVG layout variant backed by named SVG frames.

Prop	Type	Description
`svg`	`string`	Raw SVG template string used when no frame is selected. The runtime resolves `{{state.}}`, `{{timers.}}`, and `{{meta.*}}` placeholders before rendering.
`frames`	`SvgTemplateFrame[]`	Named SVG frames for click-driven or timer-driven frame changes.
`frameIdPath`	`string`	Optional state/runtime path that resolves to the active frame id. Examples: `state.frame`, `state.widgets.{{state.activeIndex}}.frame`, or `{{state.frame}}`.
`defaultFrameId`	`string`	Frame id used when `frameIdPath` is missing or resolves to an unknown frame.
`width`	`number`	Nominal SVG width used for scaling hotspots.
`height`	`number`	Nominal SVG height used for scaling hotspots.
`hotspots`	`SvgTemplateHotspot[]`	Interactive overlay regions.

SvgTemplateActionDefinition

Declarative action attached to one or more hotspots.

Prop	Type	Description
`id`	`string`	Stable action identifier.
`eventName`	`string`	Optional event name used in the action log.
`label`	`string`	Optional UI label.
`patches`	`SvgTemplateStatePatch[]`	Ordered state mutations executed when the action runs.
`timerMutations`	`SvgTemplateTimerMutation[]`	Ordered timer mutations executed when the action runs.
`frameMutations`	`SvgTemplateFrameMutation[]`	Ordered frame mutations executed when the action runs.
`openUrl`	`string`	Optional deep link opened by the host widget when the action runs.

SvgTemplateStatePatch

Declarative mutation applied to the stored activity state.

Prop	Type	Description
`op`	`'set' \| 'increment' \| 'toggle' \| 'unset' \| 'timestamp'`	Mutation operation.
`path`	`string`	Destination state path. The path may itself contain `{{...}}` placeholders.
`value`	`JsonValue`	Optional literal value used by the mutation.
`valuePath`	`string`	Optional source path used to copy a value from the current runtime scope. The path may itself contain `{{...}}` placeholders.
`valueTemplate`	`string`	Optional template-resolved value. If the string is a single `{{...}}` token, the raw referenced JSON value is copied. Otherwise the resolved string is stored.
`amount`	`number`	Increment amount for `increment`.

SvgTemplateTimerMutation

Declarative timer mutation triggered by an action.

Prop	Type	Description
`op`	`'toggle' \| 'start' \| 'stop' \| 'restart' \| 'pause' \| 'resume' \| 'reset' \| 'setDuration'`	Mutation operation.
`timerId`	`string`	Target timer identifier.
`durationMs`	`number`	Optional fixed duration override in milliseconds.
`durationPath`	`string`	Optional path that resolves to a duration override in milliseconds. The path may itself contain `{{...}}` placeholders.

SvgTemplateFrameMutation

Declarative frame mutation triggered by an action.

Prop	Type	Description
`op`	`'set' \| 'toggle' \| 'next' \| 'previous'`	Mutation operation.
`path`	`string`	Destination state path that stores the active frame id. The path may itself contain `{{...}}` placeholders.
`frameId`	`string`	Frame id used by `set`, or the alternate frame id used by `toggle`. The value may contain `{{...}}` placeholders.
`frameIds`	`string[]`	Ordered frame ids used by `next`, `previous`, and `toggle`. When omitted, `surface` can be used to read frame ids from a layout definition.
`surface`	`SvgTemplateSurface`	Optional surface whose layout frames should be used when `frameIds` is omitted.
`wrap`	`boolean`	Whether `next` and `previous` wrap at the ends. Defaults to `true`.

SvgTemplateTimerDefinition

Timer binding exposed to SVG templates.

Prop	Type	Description
`id`	`string`	Stable timer identifier.
`durationMs`	`number`	Optional fixed duration in milliseconds.
`durationPath`	`string`	Optional state path that resolves to a duration in milliseconds. The path may itself contain `{{...}}` placeholders.
`startAtPath`	`string`	Optional state path that resolves to the timer start timestamp in milliseconds. The path may itself contain `{{...}}` placeholders.
`autoStart`	`boolean`	When true, the timer starts automatically when the activity is created.

SvgTemplateTimerState

Persisted timer runtime state.

Prop	Type	Description
`id`	`string`	Timer identifier.
`startedAt`	`number \| null`	Start timestamp in milliseconds, or `null` when the timer is idle.
`elapsedMs`	`number`	Elapsed milliseconds already accumulated before the current run. This is used to preserve timer progress while paused.
`durationMs`	`number`	Current timer duration in milliseconds.
`status`	`'idle' \| 'running' \| 'paused' \| 'finished' \| 'stopped'`	Current timer status.
`updatedAt`	`number`	Last update timestamp.

StartTemplateActivityOptions

Options for starting a generic SVG template activity.

Prop	Type	Description
`activityId`	`string`	Optional explicit activity identifier. When omitted, the native runtime creates one.
`definition`	`SvgTemplateDefinition`	Generic SVG template definition.
`state`	`SvgTemplateState`	Initial JSON state exposed under `state.*`.
`openUrl`	`string`	Optional deep link used when the widget body is tapped.

TemplateActivityResult

Result when reading or updating a single activity.

Prop	Type	Description
`activity`	`SvgTemplateActivityRecord \| null`	Stored activity snapshot, or `null` when not found.

UpdateTemplateActivityOptions

Options for updating an existing template activity.

Prop	Type	Description
`activityId`	`string`	Activity identifier returned by `startTemplateActivity`.
`definition`	`SvgTemplateDefinition`	Optional replacement definition.
`state`	`SvgTemplateState`	Optional replacement state.
`openUrl`	`string`	Optional replacement deep link.

EndTemplateActivityOptions

Options for ending a template activity.

Prop	Type	Description
`activityId`	`string`	Activity identifier returned by `startTemplateActivity`.
`state`	`SvgTemplateState`	Optional final state persisted before ending.

PerformTemplateActionResult

Result after executing an action.

Prop	Type	Description
`activity`	`SvgTemplateActivityRecord`	Updated activity snapshot.
`event`	`SvgTemplateActionEvent`	Action event emitted by the runtime.

SvgTemplateActionEvent

Event emitted whenever a declarative action is executed.

Prop	Type	Description
`eventId`	`string`	Stable event identifier.
`activityId`	`string`	Activity identifier associated with the event.
`actionId`	`string`	Action identifier that produced the event.
`eventName`	`string`	Optional event name copied from the action definition.
`sourceId`	`string`	Optional source identifier, typically the hotspot id that triggered the action.
`createdAt`	`number`	Event creation timestamp in milliseconds.
`acknowledgedAt`	`number \| null`	Timestamp in milliseconds when the app acknowledged the event.
`payload`	`JsonObject \| null`	Optional caller-provided payload.
`state`	`SvgTemplateState`	State snapshot after the action was applied.
`timers`	`Record<string, SvgTemplateTimerState>`	Timer snapshot after the action was applied.

PerformTemplateActionOptions

Options for executing a declarative action.

Prop	Type	Description
`activityId`	`string`	Activity identifier returned by `startTemplateActivity`.
`actionId`	`string`	Action identifier declared in the template definition.
`sourceId`	`string`	Optional source identifier, typically the hotspot id that triggered the action.
`payload`	`JsonObject`	Optional payload stored with the emitted event and exposed to declarative patches under `{{action.payload.*}}`.

GetTemplateActivityOptions

Options for reading one stored activity.

Prop	Type	Description
`activityId`	`string`	Activity identifier to load.

ListTemplateActivitiesResult

Result when listing stored activities.

Prop	Type	Description
`activities`	`SvgTemplateActivityRecord[]`	Stored activity snapshots.

ListTemplateEventsResult

Result when listing action events.

Prop	Type	Description
`events`	`SvgTemplateActionEvent[]`	Matching action events.

ListTemplateEventsOptions

Options when listing action events.

Prop	Type	Description
`activityId`	`string`	Optional activity filter.
`unacknowledgedOnly`	`boolean`	When true, only unacknowledged events are returned.

AcknowledgeTemplateEventsOptions

Options for acknowledging events after the host app processes them.

Prop	Type	Description
`eventIds`	`string[]`	Optional explicit event ids to acknowledge.
`activityId`	`string`	Optional activity id shortcut that acknowledges every event for the activity.

StartWidgetSessionResult

Result when starting a full-native widget session.

Prop	Type	Description
`session`	`WidgetSessionRecord`	Stored session snapshot.

WidgetSessionRecord

Stored full-native widget session.

Prop	Type	Description
`widgetId`	`string`	Stable widget/session identifier.
`kind`	`string`	Optional product-defined session kind.
`state`	`JsonObject`	JSON state shared synchronously between the app and native widget code.
`metadata`	`JsonObject`	Optional JSON metadata for native widget code.
`status`	`'active' \| 'stopped'`	Current session status.
`createdAt`	`number`	Creation timestamp.
`updatedAt`	`number`	Last update timestamp.
`revision`	`number`	Monotonic revision incremented on every session state change.

StartWidgetSessionOptions

Options for starting a full-native widget session.

Prop	Type	Description
`widgetId`	`string`	Optional explicit widget/session identifier. When omitted, the native runtime creates one.
`kind`	`string`	Optional product-defined session kind.
`state`	`JsonObject`	Initial shared state.
`metadata`	`JsonObject`	Optional metadata for native widget code.

WidgetSessionResult

Result when reading or updating one full-native widget session.

Prop	Type	Description
`session`	`WidgetSessionRecord \| null`	Stored session snapshot, or `null` when not found.

UpdateWidgetSessionOptions

Options for updating a full-native widget session.

Prop	Type	Description
`widgetId`	`string`	Widget/session identifier returned by `startWidgetSession`.
`state`	`JsonObject`	Replacement or merge patch for shared state.
`metadata`	`JsonObject`	Replacement or merge patch for metadata.
`merge`	`boolean`	When true, object values are deep-merged instead of replaced.

StopWidgetSessionOptions

Options for stopping a full-native widget session.

Prop	Type	Description
`widgetId`	`string`	Widget/session identifier returned by `startWidgetSession`.
`state`	`JsonObject`	Optional final shared state.

GetWidgetSessionOptions

Options for reading one full-native widget session.

Prop	Type	Description
`widgetId`	`string`	Widget/session identifier to load.

ListWidgetSessionsResult

Result when listing full-native widget sessions.

Prop	Type	Description
`sessions`	`WidgetSessionRecord[]`	Stored session snapshots.

SendWidgetMessageResult

Result after sending a widget bridge message.

Prop	Type	Description
`message`	`WidgetBridgeMessage`	Stored message snapshot.

WidgetBridgeMessage

Queued message used for async app/widget jobs.

Prop	Type	Description
`messageId`	`string`	Stable message identifier.
`widgetId`	`string`	Widget/session identifier associated with the message.
`direction`	`WidgetMessageDirection`	Message direction.
`name`	`string`	Product-defined message or job name.
`payload`	`JsonObject \| null`	Optional JSON payload.
`expectsResponse`	`boolean`	Whether the sender expects a later response.
`status`	`WidgetMessageStatus`	Current message status.
`createdAt`	`number`	Message creation timestamp.
`acknowledgedAt`	`number \| null`	Timestamp in milliseconds when the receiver acknowledged the message.
`completedAt`	`number \| null`	Timestamp in milliseconds when the message was completed or failed.
`response`	`JsonObject \| null`	Optional JSON response for async jobs.
`error`	`string \| null`	Optional failure message for async jobs.

SendWidgetMessageOptions

Options for sending a full-native widget bridge message.

Prop	Type	Description
`widgetId`	`string`	Widget/session identifier associated with the message.
`name`	`string`	Product-defined message or job name.
`direction`	`WidgetMessageDirection`	Optional message direction. Defaults to `appToWidget` when called from the app.
`payload`	`JsonObject`	Optional JSON payload.
`expectsResponse`	`boolean`	Whether the sender expects a later response.

ListWidgetMessagesResult

Result when listing full-native widget bridge messages.

Prop	Type	Description
`messages`	`WidgetBridgeMessage[]`	Matching messages.

ListWidgetMessagesOptions

Options when listing full-native widget bridge messages.

Prop	Type	Description
`widgetId`	`string`	Optional widget/session filter.
`direction`	`WidgetMessageDirection`	Optional direction filter.
`unacknowledgedOnly`	`boolean`	When true, only unacknowledged messages are returned.
`pendingOnly`	`boolean`	When true, only pending messages are returned.

AcknowledgeWidgetMessagesOptions

Options for acknowledging widget bridge messages after processing them.

Prop	Type	Description
`messageIds`	`string[]`	Optional explicit message ids to acknowledge.
`widgetId`	`string`	Optional widget/session shortcut that acknowledges matching messages.
`direction`	`WidgetMessageDirection`	Optional direction filter.

WidgetMessageResult

Result after completing a widget bridge message.

Prop	Type	Description
`message`	`WidgetBridgeMessage \| null`	Stored message snapshot, or `null` when not found.

CompleteWidgetMessageOptions

Options for completing an async widget bridge message.

Prop	Type	Description
`messageId`	`string`	Message identifier returned by `sendWidgetMessage`.
`response`	`JsonObject`	Optional JSON response payload.
`error`	`string`	Optional error string. When set, the message status becomes `failed`.

PluginVersionResult

Result payload for plugin version queries.

Prop	Type	Description
`version`	`string`	Native implementation version marker.

Type Aliases

SvgTemplateLayout

SVG layout variant for one WidgetKit surface.

SvgTemplateLayoutWithSvg | SvgTemplateLayoutWithFrames

JsonValue

Any JSON-safe value accepted by the plugin.

JsonPrimitive | JsonObject | JsonArray

JsonPrimitive

JSON-safe primitive value.

string | number | boolean | null

JsonArray

JSON-safe array used as activity state.

JsonValue[]

SvgTemplateSurface

Named WidgetKit surface for one SVG layout variant.

'lockScreen' | 'dynamicIslandExpanded' | 'dynamicIslandCompactLeading' | 'dynamicIslandCompactTrailing' | 'dynamicIslandMinimal'

SvgTemplateState

Structured state payload persisted for an activity.

JsonObject

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

WidgetMessageDirection

Message direction for the full-native widget bridge.

'appToWidget' | 'widgetToApp'

WidgetMessageStatus

Completion status for a full-native widget bridge message.

'pending' | 'completed' | 'failed'

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github		.github
.maestro		.maestro
android		android
example-app		example-app
ios		ios
scripts		scripts
src		src
.eslintignore		.eslintignore
.gitignore		.gitignore
.prettierignore		.prettierignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CapgoCapacitorWidgetKit.podspec		CapgoCapacitorWidgetKit.podspec
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
bun.lock		bun.lock
package.json		package.json
renovate.json		renovate.json
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation