Getting Started

1. Install the plugin

   npm

   npm i @capgo/capacitor-live-activities

   pnpm

   pnpm add @capgo/capacitor-live-activities

   yarn

   yarn add @capgo/capacitor-live-activities

   bun

   bun add @capgo/capacitor-live-activities

2. Sync native platforms

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Create the Live Activity widget target

   • Create a Widget Extension target in Xcode and name it LiveActivities.
   • Add the same App Group to the main app target and the widget extension target.

Platform requirements

• iOS 16.1 or later is required.
• Live Activities are not available on Android or web, so use areActivitiesSupported() before showing related UI.

Enable Live Activities

Add the following key to your app Info.plist:

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

Add an App Group for the app and widget targets. A common pattern is:

group.YOUR_BUNDLE_ID.liveactivities

Check support

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

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

if (!supported) {
  console.warn('Live Activities unavailable:', reason);
}

Start an activity

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'vertical',
    spacing: 8,
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' },
      { type: 'progress', value: 'progress', tint: '#34C759' },
    ],
  },
  dynamicIslandLayout: {
    expanded: {
      center: { type: 'text', content: '{{status}}' },
      trailing: { type: 'text', content: '{{eta}}' },
    },
    compactLeading: { type: 'text', content: 'ETA' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'text', content: '{{eta}}' },
  },
  behavior: {
    widgetUrl: 'myapp://orders/12345',
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6,
  },
});

Update and end the activity

await CapgoLiveActivities.updateActivity({
  activityId,
  data: {
    status: 'Arriving soon',
    eta: '2 min',
    progress: 0.9,
  },
});

await CapgoLiveActivities.endActivity({
  activityId,
  data: {
    status: 'Delivered',
    progress: 1,
  },
  dismissalPolicy: 'after',
  dismissAfter: Date.now() + 60 * 60 * 1000,
});

Recommended setup

• Keep the widget extension focused on rendering and let the Capacitor app own activity creation and updates.
• Use App Groups for any shared images or data the widget needs to display.
• Model your JSON layout from the real-time state you already have in the app so updates stay simple and deterministic.