@capgo/capacitor-widget-kit

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

Demo

The plugin has two implementation paths:

• SVG template widgets: store Home Screen, Lock Screen, Dynamic Island, and Android layouts with 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

• Add a Widget Extension target for Home Screen / SpringBoard widgets.
• iOS 17+ is recommended for interactive Home Screen widget and 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
• CapgoTemplateWidgetTimelineProvider and CapgoTemplateHomeWidgetView for real iOS Home Screen / SpringBoard widgets backed by WidgetKit timelines
• CapgoTemplateWidgetBridge to load a stored SVG activity and resolve one surface into svg + width/height + frameId + hotspots + metadata
• CapgoTemplateSurfaceView, CapgoTemplateWidgetSurface, and CapgoTemplateLatestWidgetSurface to place a rendered SVG view under native hotspot buttons in SwiftUI
• 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 {
        ExampleTemplateHomeWidget()

        if #available(iOS 16.2, *) {
            ExampleTemplateLiveActivityWidget()
        }
    }
}

struct ExampleTemplateHomeWidget: Widget {
    private let kind = "ExampleTemplateHomeWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: CapgoTemplateWidgetTimelineProvider()) { entry in
            CapgoTemplateHomeWidgetView(entry: entry) { layout in
                MySvgRenderer(svg: layout.svg)
            } placeholder: {
                Text("No active widget")
            }
        }
        .configurationDisplayName("Capgo Template")
        .description("Home Screen widget rendered from the shared Capgo SVG template store.")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

Use the SwiftUI surface helpers when a custom WidgetKit view should be designed from JS but rendered by native widget code:

CapgoTemplateLatestWidgetSurface {
    layout in
    MySvgRenderer(svg: layout.svg)
} placeholder: {
    Text("No active widget")
}

The helper positions CapgoTemplateActionIntent buttons over the resolved SVG hotspots on iOS 17+. See example-app/widget-extension/ExampleWidgetBundle.swift for a complete Home Screen widget and Live Activity scaffold.

SVG Template Usage

This mode is for Home Screen, Lock Screen, Dynamic Island, and Android 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.startTemplateWidget({
  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: 'homeScreen' }],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        timerMutations: [{ op: 'toggle', timerId: 'rest' }],
      },
    ],
    layouts: {
      homeScreen: {
        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 widget for the Home Screen surface
• resolving the Home Screen surface
• running an action from the app and from a hotspot overlay
• reading the stored widget template back
• reading and acknowledging the event log
• ending the stored template

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

API

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

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

The core abstraction is a generic SVG template record:

• 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, including Home Screen / SpringBoard widgets backed by WidgetKit timelines.

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>

startTemplateWidget(...)

startTemplateWidget(options: StartTemplateWidgetOptions) => Promise<StartTemplateActivityResult>

Persist a generic SVG template for Home Screen / SpringBoard widgets without starting a Live Activity.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | StartTemplateWidgetOptions |

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>

reloadWidgets(...)

reloadWidgets(options?: ReloadWidgetsOptions | undefined) => Promise<void>

Ask native widgets to reload after external app state changes.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ReloadWidgetsOptions |

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 | | ---------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | homeScreen | SvgTemplateLayout | Optional Home Screen / SpringBoard widget layout. When omitted, native Home Screen widgets may fall back to lockScreen. | | lockScreen | SvgTemplateLayout | Optional lock-screen / Live Activity 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. | | startLiveActivity | boolean | Whether iOS should also start a native Live Activity. Defaults to true. Set to false when the same SVG template should only back a home-screen or lock-screen widget surface. |

StartTemplateWidgetOptions

Options for starting or replacing a Home Screen / SpringBoard widget template.

This persists the same SVG template record as startTemplateActivity, but native iOS implementations do not start an ActivityKit Live 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</code