📡 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
  • 🧭 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
  • 📱 Example App
  • 🛠 API
    • startActivity(...)
    • startActivityWithPush(...)
    • updateActivity(...)
    • endActivity(...)
    • isAvailable()
    • isRunning(...)
    • getCurrentActivity(...)
    • listActivities()
    • observePushToStartToken()
    • addListener('liveActivityPushToken', ...)
    • addListener('liveActivityPushToStartToken', ...)
    • addListener('liveActivityUpdate', ...)
    • Interfaces
      • StartActivityOptions
      • UpdateActivityOptions
      • AlertConfiguration
      • EndActivityOptions
      • LiveActivityState
      • ListActivitiesResult
      • Array
      • ConcatArray
      • PluginListenerHandle
      • PushTokenEvent
      • PushToStartTokenEvent
      • ActivityUpdateEvent
    • Type Aliases
      • Record

📦 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

1. Open your app’s iOS project in Xcode.
2. Go to File > New > Target…
3. Choose Widget Extension.
4. Name it e.g. LiveActivityWidget.
5. Check the box “Include Live Activity”.
6. 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:

1. Open Xcode and go to the File Navigator.
2. Expand Pods > CapacitorLiveActivity > Shared.
3. Copy GenericAttributes.swift to Widget Extension Target, e.g. LiveActivityWidget
4. 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
• Real device required (no Simulator)
• For remote flows, test with the app in background/terminated

📱 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(options: StartActivityOptions) => Promise<void>

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

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

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

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

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

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

listActivities() => Promise<ListActivitiesResult>

observePushToStartToken() => Promise<void>

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

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

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