capacitor-live-activity

v8.1.0

Published

2 months ago

A Capacitor plugin for managing iOS Live Activities using ActivityKit and Swift.

0High
0Medium
0Low

kisimedia

capacitor live-activity activitykit ios plugin swift capacitor-plugin

📡 capacitor-live-activity

A Capacitor plugin for managing iOS Live Activities using ActivityKit and Swift.

[!TIP] 🚀 Looking for a ready-to-run demo? → Try the Example App

🧭 Table of contents

📡 capacitor-live-activity

📦 Install

npm install capacitor-live-activity
npx cap sync

[!NOTE] This plugin requires iOS 16.2+ to work properly due to ActivityKit API usage.

[!IMPORTANT] This plugin requires a Live Activity widget extension to be present and configured in your Xcode project.
Without a widget, Live Activities will not appear on the lock screen or Dynamic Island.

🧩 Widget Setup (Required)

To use Live Activities, your app must include a widget extension that defines the UI for the Live Activity using ActivityKit. Without this, the Live Activity will not appear on the Lock Screen or Dynamic Island.

1. Add a Widget Extension in Xcode

Open your app’s iOS project in Xcode.
Go to File > New > Target…
Choose Widget Extension.
Name it e.g. LiveActivityWidget.
Check the box “Include Live Activity”.
Finish and wait for Xcode to generate the files.

2. Configure the Widget (Example)

Make sure the widget uses the same attribute type as the plugin (e.g. GenericAttributes.swift):

import ActivityKit
import WidgetKit
import SwiftUI

struct LiveActivityWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: GenericAttributes.self) { context in
            // Lock Screen UI
            VStack {
                Text(context.state.values["title"] ?? "⏱")
                Text(context.state.values["status"] ?? "-")
            }
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text(context.state.values["title"] ?? "")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text(context.state.values["status"] ?? "")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text(context.state.values["message"] ?? "")
                }
            } compactLeading: {
                Text("🔔")
            } compactTrailing: {
                Text(context.state.values["status"] ?? "")
            } minimal: {
                Text("🎯")
            }
        }
    }
}

3. Add GenericAttributes.swift to your Widget Target

To support Live Activities with dynamic values, this plugin uses a shared Swift struct called GenericAttributes.

By default, it’s located under: Pods > CapacitorLiveActivity > LiveActivityPlugin > Shared > GenericAttributes.swift

To make it available in your widget extension:

Open Xcode and go to the File Navigator.
Expand Pods > CapacitorLiveActivity > Shared.
Copy GenericAttributes.swift to Widget Extension Target, e.g. LiveActivityWidget
Make sure to select "Copy files to destination"

Why is this needed?

Xcode doesn’t automatically include files from a CocoaPods plugin into your widget target. Without this step, your widget won’t compile because it cannot find GenericAttributes.

4. Add Capability

Go to your main app target → Signing & Capabilities tab and add:

Background Modes → Background fetch
Go to your app target → Signing & Capabilities:
- ✅ Push Notifications
- ✅ Live Activities

5. Ensure Inclusion in Build

In your App target’s Info.plist, ensure:

<key>NSSupportsLiveActivities</key>
<true/>

Clean and rebuild the project (Cmd + Shift + K, then Cmd + B).

🧠 Platform behavior

iOS 16.2+: Live Activities (local start/update/end)
iOS 17.2+: Remote start via push (push-to-start) and per-activity push updates
iOS 26.0+: Schedule Live Activities to start at a future date
Real device required (no Simulator)
For remote flows, test with the app in background/terminated

💡 Usage Examples

Basic Live Activity

import { LiveActivity } from 'capacitor-live-activity';

// Start a basic Live Activity
await LiveActivity.startActivity({
  id: 'my-activity',
  attributes: {
    title: 'Delivery',
  },
  contentState: {
    status: 'On the way',
    eta: '15 min',
  },
});

// Update it
await LiveActivity.updateActivity({
  id: 'my-activity',
  contentState: {
    status: 'Almost there!',
    eta: '2 min',
  },
});

// End it
await LiveActivity.endActivity({
  id: 'my-activity',
  contentState: {
    status: 'Delivered',
    eta: '0 min',
  },
});

Scheduled Live Activity (iOS 26+)

Schedule a Live Activity to start at a future date, perfect for upcoming events like sports games, meetings, or deliveries:

import { LiveActivity } from 'capacitor-live-activity';

// Schedule a Live Activity to start in 2 hours
const futureDate = Date.now() / 1000 + 2 * 60 * 60; // UNIX timestamp in seconds

await LiveActivity.startActivityScheduled({
  id: 'game-activity',
  attributes: {
    homeTeam: 'Warriors',
    awayTeam: 'Lakers',
  },
  contentState: {
    status: 'Scheduled',
    startTime: '7:30 PM',
  },
  startDate: futureDate,
  alertConfiguration: {
    title: 'Game Starting Soon!',
    body: 'Warriors vs Lakers begins in 15 minutes',
    sound: 'default',
  },
  enablePushToUpdate: true, // Optional: enable push updates
  style: 'standard', // Optional: 'standard' or 'transient'
});

// The activity will automatically start at the scheduled time
// Listen for push tokens if enablePushToUpdate is true
LiveActivity.addListener('liveActivityPushToken', (event) => {
  console.log('Push token:', event.token);
  // Send this token to your server for push updates
});

📱 Example App

This plugin includes a fully functional demo app under the example-app/ directory.

The demo is designed to run on real iOS devices and showcases multiple Live Activity types like delivery, timer, taxi, workout, and more.

Launch and test various Live Activities interactively
Trigger updates and alert banners
View JSON state changes in a live log console

[!NOTE] For full instructions, see example-app/README.md

🛠 API

startActivity(...)

startActivity(options: StartActivityOptions) => Promise<void>

Start a new Live Activity with local (on-device) ActivityKit.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | StartActivityOptions |

Since: 0.0.1

startActivityWithPush(...)

startActivityWithPush(options: StartActivityOptions) => Promise<{ activityId: string; }>

Start a new Live Activity locally with push support (pushType: .token).

The per-activity APNs/FCM live-activity token will be emitted via the "liveActivityPushToken" event shortly after starting.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | StartActivityOptions |

Returns: Promise<{ activityId: string; }>

Since: 7.1.0

startActivityScheduled(...)

startActivityScheduled(options: ScheduledActivityOptions) => Promise<{ activityId: string; }>

Schedule a new Live Activity to start at a future date (iOS 26+).

The activity will start at the specified date even if the app is in the background. An alert configuration is required to notify the user when the activity starts.

Note: Scheduled activities count towards the system limit for simultaneous Live Activities. The activity state will be pending until the scheduled start time.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | ScheduledActivityOptions |

Returns: Promise<{ activityId: string; }>

Since: 8.1.0

updateActivity(...)

updateActivity(options: UpdateActivityOptions) => Promise<void>

Update an existing Live Activity (identified by your logical id).

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | UpdateActivityOptions |

Since: 0.0.1

endActivity(...)

endActivity(options: EndActivityOptions) => Promise<void>

End an existing Live Activity (identified by your logical id).

Optionally provide a final state and a dismissal policy.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | EndActivityOptions |

Since: 0.0.1

isAvailable()

isAvailable() => Promise<{ value: boolean; }>

Return whether Live Activities are enabled and allowed on this device.

Note: This method resolves to { value: boolean } to match native.

Returns: Promise<{ value: boolean; }>

Since: 0.0.1

isRunning(...)

isRunning(options: { id: string; }) => Promise<{ value: boolean; }>

Return whether a Live Activity with the given logical id is currently running.

Note: This method resolves to { value: boolean } to match native.

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<{ value: boolean; }>

Since: 0.0.1

getCurrentActivity(...)

getCurrentActivity(options?: { id?: string | undefined; } | undefined) => Promise<LiveActivityState | undefined>

Get the current Live Activity state.

If an id is provided, returns that specific activity. If no id is given, returns the most recently started activity.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<LiveActivityState>

Since: 0.0.1

listActivities()

listActivities() => Promise<ListActivitiesResult>

List known activities (ActivityKit active/stale/pending etc.) for the shared GenericAttributes type.

Useful to discover activities that were started via push once the process becomes aware of them.

Returns: Promise<ListActivitiesResult>

Since: 7.1.0

observePushToStartToken()

observePushToStartToken() => Promise<void>

iOS 17.2+: begin streaming the global push-to-start token.

The token will be emitted via "liveActivityPushToStartToken".

Since: 7.1.0

addListener('liveActivityPushToken', ...)

addListener(eventName: 'liveActivityPushToken', listenerFunc: (event: PushTokenEvent) => void) => Promise<PluginListenerHandle>

Emitted when a per-activity live-activity push token becomes available after calling startActivityWithPush.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | eventName | 'liveActivityPushToken' | | listenerFunc | (event: PushTokenEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 7.1.0

addListener('liveActivityPushToStartToken', ...)

addListener(eventName: 'liveActivityPushToStartToken', listenerFunc: (event: PushToStartTokenEvent) => void) => Promise<PluginListenerHandle>

Emitted when a global push-to-start token is available (iOS 17.2+).

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'liveActivityPushToStartToken' | | listenerFunc | (event: PushToStartTokenEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 7.1.0

addListener('liveActivityUpdate', ...)

addListener(eventName: 'liveActivityUpdate', listenerFunc: (event: ActivityUpdateEvent) => void) => Promise<PluginListenerHandle>

Emitted when the lifecycle of a Live Activity changes (e.g. active → stale).

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'liveActivityUpdate' | | listenerFunc | (event: ActivityUpdateEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 7.1.0

Interfaces

StartActivityOptions

Options for starting a Live Activity.

| Prop | Type | Description | | ------------------ | --------------------------------------------------------------- | ----------------------------------------------------- | | id | string | Logical identifier you use to reference the activity. | | attributes | Record<string, string> | Immutable attributes for the activity. | | contentState | Record<string, string> | Initial dynamic content state. | | timestamp | number | Optional UNIX timestamp when the activity started. |

ScheduledActivityOptions

Options for scheduling a Live Activity to start at a future date (iOS 26+).

| Prop | Type | Description | Default | | ------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | id | string | Logical identifier you use to reference the activity. | | | attributes | Record<string, string> | Immutable attributes for the activity. | | | contentState | Record<string, string> | Initial dynamic content state. | | | startDate | number | UNIX timestamp (in seconds) when the Live Activity should start. Must be in the future. The system will start the activity at this time even if the app is in the background. | | | alertConfiguration | AlertConfiguration | Alert configuration to notify the user when the activity starts. Required for scheduled activities to inform users about the started Live Activity. | | | enablePushToUpdate | boolean | Whether to enable push notifications for this activity. If true, the activity will receive push token updates via the liveActivityPushToken event. | false | | style | 'standard' | 'transient' | Activity style: 'standard' or 'transient'. - 'standard': Activity continues until explicitly ended or max duration reached. - 'transient': Activity appears in Dynamic Island but ends automatically when device locks. | 'standard' |

AlertConfiguration

Alert configuration shown for certain updates.

| Prop | Type | Description | | ----------- | ------------------- | -------------------------------------- | | title | string | Optional title of the alert. | | body | string | Optional body text of the alert. | | sound | string | Optional sound file name or "default". |

UpdateActivityOptions

Options for updating a Live Activity.

| Prop | Type | Description | | ------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | | id | string | Logical identifier of the activity to update. | | contentState | Record<string, string> | Updated dynamic content state. | | alert | AlertConfiguration | Optional alert configuration to show a notification banner or Apple Watch alert. | | timestamp | number | Optional UNIX timestamp for the update. |

EndActivityOptions

Options for ending a Live Activity.

| Prop | Type | Description | | ------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | id | string | Logical identifier of the activity to end. | | contentState | Record<string, string> | Final dynamic content state to render before dismissal. | | timestamp | number | Optional UNIX timestamp for the end event. | | dismissalDate | number | Optional future dismissal time (UNIX). If omitted, the system default dismissal policy applies. |

LiveActivityState

Represents the state of a Live Activity returned by the plugin.

| Prop | Type | Description | | --------------- | --------------------------------------------------------------- | ------------------------------------------------------ | | id | string | System activity identifier (Activity.id). | | values | Record<string, string> | Current dynamic values. | | isStale | boolean | Whether the activity is stale. | | isEnded | boolean | Whether the activity has ended. | | startedAt | string | ISO string of when the activity started (if provided). |

ListActivitiesResult

Result of listing activities.

| Prop | Type | | ----------- | ----------------------------------------------------------------- | | items | { id: string; activityId: string; state: string; }[] |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

PushTokenEvent

Event payload for per-activity live-activity push tokens.

| Prop | Type | Description | | ---------------- | ------------------- | ----------------------------------------------------------- | | id | string | Your logical ID (the one you passed to start). | | activityId | string | System activity identifier (Activity.id). | | token | string | Hex-encoded APNs/FCM live activity token for this activity. |

PushToStartTokenEvent

Event payload for the global push-to-start token (iOS 17.2+).

| Prop | Type | Description | | ----------- | ------------------- | ----------------------------------------------------- | | token | string | Hex-encoded APNs/FCM push-to-start token (iOS 17.2+). |

ActivityUpdateEvent

Event payload for activity lifecycle updates.

| Prop | Type | Description | | ---------------- | ------------------- | ----------------------------------------- | | id | string | Your logical ID (attributes.id). | | activityId | string | System activity identifier (Activity.id). | | state | string | ActivityKit state as a string. |

Type Aliases

Record

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

{ [P in K]: T; }

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

📡 capacitor-live-activity

🧭 Table of contents

📦 Install

🧩 Widget Setup (Required)

1. Add a Widget Extension in Xcode

2. Configure the Widget (Example)

3. Add GenericAttributes.swift to your Widget Target

To make it available in your widget extension:

Why is this needed?

4. Add Capability

5. Ensure Inclusion in Build

🧠 Platform behavior

💡 Usage Examples

Basic Live Activity

Scheduled Live Activity (iOS 26+)

📱 Example App

🛠 API

startActivity(...)

startActivityWithPush(...)

startActivityScheduled(...)

updateActivity(...)

endActivity(...)

isAvailable()

isRunning(...)

getCurrentActivity(...)

listActivities()

observePushToStartToken()

addListener('liveActivityPushToken', ...)

addListener('liveActivityPushToStartToken', ...)

addListener('liveActivityUpdate', ...)

Interfaces

StartActivityOptions

ScheduledActivityOptions

AlertConfiguration

UpdateActivityOptions

EndActivityOptions

LiveActivityState

ListActivitiesResult

PluginListenerHandle

PushTokenEvent

PushToStartTokenEvent

ActivityUpdateEvent

Type Aliases

Record