@capgo/capacitor-live-activities

Manage iOS Live Activities from Capacitor with a powerful JSON-based layout system.

Why Capacitor Live Activities?

• iOS 16.1+ Live Activities - Full integration with Apple's Live Activities framework
• Dynamic Island Support - Seamless integration with iPhone 14 Pro+ Dynamic Island
• JSON Layout System - Build complex layouts declaratively without Swift code
• Real-time Updates - Update your activities dynamically from your app
• Image Management - Save and use images in your Live Activities via App Groups
• Cross-platform Safe - Graceful fallbacks on Android and web

Essential for delivery tracking apps, sports scores, ride-sharing, timers, and any app needing real-time lock screen updates.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/live-activities/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-live-activities
bunx cap sync

Requirements

• iOS 16.1+ - Live Activities require iOS 16.1 or later
• Widget Extension - You must create a Widget Extension target in Xcode
• App Groups - Required for sharing data between app and widget

iOS Setup

1. Create Widget Extension

In Xcode:

1. File → New → Target
2. Select "Widget Extension"
3. Name it exactly: LiveActivities
4. Uncheck "Include Configuration Intent"

2. Configure App Groups

1. Select your main app target → Signing & Capabilities
2. Add "App Groups" capability
3. Create group: group.YOUR_BUNDLE_ID.liveactivities
4. Add the same App Group to your Widget Extension target

3. Enable Live Activities in Info.plist

Add to your app's Info.plist:

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

4. Create the Widget Bundle

In your Widget Extension, create LiveActivitiesBundle.swift:

import WidgetKit
import SwiftUI

@main
struct LiveActivitiesBundle: WidgetBundle {
    var body: some Widget {
        // Your Live Activity widget goes here
        LiveActivityWidget()
    }
}

Usage Examples

Check Support

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

const checkSupport = async () => {
  const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
  if (supported) {
    console.log('Live Activities are supported!');
  } else {
    console.log('Not supported:', reason);
  }
};

Start a Delivery Tracking Activity

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

const startDeliveryActivity = async () => {
  const { activityId } = await CapgoLiveActivities.startActivity({
    layout: {
      type: 'container',
      direction: 'vertical',
      spacing: 8,
      children: [
        {
          type: 'container',
          direction: 'horizontal',
          children: [
            { type: 'image', source: 'sfSymbol', value: 'box.truck.fill', width: 24, height: 24, tintColor: '#007AFF' },
            { 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: {
        leading: { type: 'image', source: 'sfSymbol', value: 'box.truck.fill', tintColor: '#007AFF' },
        trailing: { type: 'text', content: '{{eta}}', fontWeight: 'semibold' },
        center: { type: 'text', content: '{{status}}', fontSize: 14 },
        bottom: { type: 'progress', value: 'progress', tint: '#34C759' }
      },
      compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck.fill' },
      compactTrailing: { type: 'text', content: '{{eta}}' },
      minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck.fill' }
    },
    behavior: {
      widgetUrl: 'myapp://order/12345'
    },
    data: {
      orderNumber: '12345',
      status: 'On the way',
      eta: '10 min',
      progress: 0.6
    }
  });

  console.log('Started activity:', activityId);
  return activityId;
};

Update an Activity

const updateActivity = async (activityId: string) => {
  await CapgoLiveActivities.updateActivity({
    activityId,
    data: {
      status: 'Arriving soon!',
      eta: '2 min',
      progress: 0.9
    },
    alertConfiguration: {
      title: 'Delivery Update',
      body: 'Your order is almost there!'
    }
  });
};

End an Activity

const endActivity = async (activityId: string) => {
  await CapgoLiveActivities.endActivity({
    activityId,
    data: {
      status: 'Delivered!',
      progress: 1.0
    },
    dismissalPolicy: 'after',
    dismissAfter: Date.now() + 3600000 // Keep visible for 1 hour
  });
};

Timer Example (Countdown)

const startTimerActivity = async () => {
  const targetDate = Date.now() + 1800000; // 30 minutes from now

  const { activityId } = await CapgoLiveActivities.startActivity({
    layout: {
      type: 'container',
      direction: 'horizontal',
      spacing: 16,
      children: [
        { type: 'image', source: 'sfSymbol', value: 'timer', width: 32, height: 32 },
        {
          type: 'container',
          direction: 'vertical',
          children: [
            { type: 'text', content: '{{title}}', fontSize: 16, fontWeight: 'bold' },
            { type: 'timer', targetDate: 'endTime', style: 'timer', fontSize: 24, fontWeight: 'bold', color: '#FF3B30' }
          ]
        }
      ]
    },
    dynamicIslandLayout: {
      expanded: {
        center: { type: 'text', content: '{{title}}' },
        bottom: { type: 'timer', targetDate: 'endTime', style: 'timer', fontSize: 32 }
      },
      compactLeading: { type: 'image', source: 'sfSymbol', value: 'timer' },
      compactTrailing: { type: 'timer', targetDate: 'endTime', style: 'timer' },
      minimal: { type: 'timer', targetDate: 'endTime', style: 'timer' }
    },
    data: {
      title: 'Cooking Timer',
      endTime: targetDate
    }
  });

  return activityId;
};

Using Saved Images

// Save an image first
const { imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-thumbnail',
  compressionQuality: 0.8
});

// Use in activity layout
const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'image', source: 'saved', value: imageName, width: 48, height: 48, properties: { cornerRadius: 8 } },
      { type: 'text', content: '{{productName}}', fontSize: 16 }
    ]
  },
  // ... rest of config
});

// Cleanup when done
await CapgoLiveActivities.cleanupImages();

Layout Elements

Container

Groups child elements horizontally, vertically, or stacked.

{
  type: 'container',
  direction: 'horizontal' | 'vertical' | 'zstack',
  alignment: 'leading' | 'center' | 'trailing' | 'top' | 'bottom',
  spacing: 8,
  children: [/* ... */],
  properties: { padding: 12, backgroundColor: '#F5F5F5', cornerRadius: 8 }
}

Text

Displays text with styling and variable interpolation.

{
  type: 'text',
  content: 'Hello {{name}}!',
  fontSize: 16,
  fontWeight: 'bold',
  color: '#000000',
  alignment: 'center',
  lineLimit: 2,
  fontDesign: 'rounded'
}

Image

Displays images from various sources.

// SF Symbol
{ type: 'image', source: 'sfSymbol', value: 'star.fill', tintColor: '#FFD700' }

// URL
{ type: 'image', source: 'url', value: 'https://example.com/image.png', width: 48, height: 48 }

// Saved image
{ type: 'image', source: 'saved', value: 'my-saved-image' }

// Asset from bundle
{ type: 'image', source: 'asset', value: 'logo' }

Progress

Shows a progress bar.

{
  type: 'progress',
  value: 'progressValue', // Key in data object (0-1)
  tint: '#34C759'
}

Timer

Displays a countdown or elapsed time.

{
  type: 'timer',
  targetDate: 'endTime', // Key in data object (timestamp)
  style: 'timer' | 'relative' | 'offset',
  fontSize: 24,
  color: '#FF3B30',
  pausesOnReach: true
}

Gauge

Circular progress indicator.

{
  type: 'gauge',
  value: 'level', // Key in data (0-1)
  style: 'accessoryCircular',
  label: 'Battery',
  tint: '#34C759'
}

Spacer

Flexible space between elements.

{ type: 'spacer', minLength: 8 }

API

areActivitiesSupported() => Promise<AreActivitiesSupportedResult>

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

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

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

getAllActivities() => Promise<GetAllActivitiesResult>

saveImage(options: SaveImageOptions) => Promise<SaveImageResult>

removeImage(options: RemoveImageOptions) => Promise<RemoveImageResult>

listImages() => Promise<ListImagesResult>

cleanupImages() => Promise<void>

getPluginVersion() => Promise<{ version: string; }>

startTimerSequence(options: TimerSequenceOptions) => Promise<TimerSequenceResult>

pauseTimerSequence(options: { sequenceId: string; }) => Promise<void>

resumeTimerSequence(options: { sequenceId: string; }) => Promise<void>

stopTimerSequence(options: { sequenceId: string; }) => Promise<void>

skipTimerStep(options: { sequenceId: string; }) => Promise<void>

previousTimerStep(options: { sequenceId: string; }) => Promise<void>

getTimerState(options: GetTimerStateOptions) => Promise<TimerSequenceState>

addListener(eventName: 'timerSequenceEvent', callback: TimerSequenceCallback) => Promise<{ remove: () => Promise<void>; }>

Credits

Inspired by ludufre/capacitor-live-activities with a simplified API and Capgo integration.