capacitor-live-activities

Live Activities

capacitor-live-activities

Ionic Capacitor plugin for Live Activities for iOS 16.2+

Maintainers

| Maintainer | GitHub | Social | LinkedIn |
| ---------------------- | ------------------------------------- | --------------------------------- | ------------------------------------------------------------------ |
| Luan Freitas (ludufre) | ludufre | @ludufre | Luan Freitas |

✨ Features

- 🏃‍♂️ Easy Integration: Simple installation with automatic configuration
- 🎨 Flexible Layouts: JSON-based layout system with containers, text, images, progress, and timers
- 📱 Dynamic Island Support: Full support for iPhone 14 Pro+ Dynamic Island states
- 🔄 Real-time Updates: Live data updates with push notifications
- 🖼️ Rich Media: Support for SF Symbols, images, gradients, and custom styling
- ⏱️ Timer Integration: Built-in countdown and relative time displays
- 📊 Progress Tracking: Visual progress bars and completion indicators
- 🎯 Multiple Examples: Comprehensive examples including sports scoreboards and food delivery tracking

🎯 JSON Layout System

Create beautiful Live Activities using a declarative JSON structure:

``typescript
const result = await LiveActivities.startActivity({
layout: {
type: "container",
properties: [{ direction: "vertical" }, { spacing: 12 }],
children: [
{
type: "text",
properties: [{ text: "{{title}}" }, { fontSize: 18 }]
}
]
},
data: { title: "Hello Live Activity!" }
});
`

🧑🏻‍🏫 Documentation & How-to

🚀 Quick Start

$3

`bash
npm install capacitor-live-activities
npx cap sync
`

$3

1. Open your iOS project in Xcode
2. Add Widget Extension Target:
- File → New → Target
- Select "Widget Extension"
- Product Name: LiveActivities (exactly as shown)
- Uncheck all options: Include Live Activity, Include Control, Include Configuration App Intent
- Click "Finish"
- Choose Don't Activate when prompted

3. Convert to Group:
- Right-click on LiveActivities folder in Xcode
- Select "Convert to Group"

$3

Add the LiveActivitiesKit dependency to your ios/App/Podfile:

`ruby
target 'LiveActivitiesExtension' do
pod 'LiveActivitiesKit', :path => '../../node_modules/capacitor-live-activities'
end
`

$3

Add Live Activities support to your ios/App/Info.plist:

`xml
NSSupportsLiveActivities

`

$3

Replace the content of ios/App/LiveActivities/LiveActivitiesBundle.swift:

`swift
import WidgetKit
import SwiftUI
import LiveActivitiesKit

@main
struct LiveActivitiesBundle: WidgetBundle {
var body: some Widget {
LiveActivities()
DynamicActivityWidget()
}
}
`

$3

1. In Xcode, select your main app target
2. Go to Signing & Capabilities
3. Add App Groups capability
4. Create new App Group: group.YOUR_BUNDLE_ID.liveactivities
- Example: group.com.example.myapp.liveactivities
5. Repeat for Widget Extension target

$3

`typescript
import { LiveActivities } from 'capacitor-live-activities';

// Start a Live Activity
const result = await LiveActivities.startActivity({
layout: {
type: 'container',
properties: [
{ direction: 'vertical' },
{ spacing: 12 },
{ padding: 16 },
{ backgroundColor: '#ffffff' },
{ cornerRadius: 12 },
],
children: [
{
type: 'text',
properties: [
{ text: '{{title}}' },
{ fontSize: 18 },
{ fontWeight: 'bold' },
{ color: '#1a1a1a' },
{ alignment: 'center' },
],
},
],
},
dynamicIslandLayout: {
expanded: {
leading: {
type: 'text',
properties: [{ text: 'Left' }],
},
center: {
type: 'text',
properties: [{ text: 'Center' }],
},
trailing: {
type: 'text',
properties: [{ text: 'Right' }],
},

bottom: {
type: 'text',
properties: [{ text: '{{title}}' }],
},
},
compactLeading: {
type: 'image',
properties: [{ systemName: 'face.smiling' }],
},
compactTrailing: {
type: 'image',
properties: [{ systemName: 'figure.walk.diamond.fill' }],
},
minimal: {
type: 'text',
properties: [{ text: 'Hi!' }],
},
},
data: {
title: 'Hello Live Activity!',
},
behavior: {
systemActionForegroundColor: '#007AFF',
widgetUrl: 'https://example.com',
keyLineTint: '#007AFF',
},
});

// Update the activity
await LiveActivities.updateActivity({
activityId: result.activityId,
data: {
title: "Updated content!"
}
});

// End the activity
await LiveActivities.endActivity({
activityId: result.activityId,
data: {
title: "Activity completed"
}
});
`

📚 Examples

This plugin includes a comprehensive example app with multiple Live Activity implementations:

$3

`bash
cd example-app
npm install # or pnpm install
npx cap run ios
ionic cap run ios
`

🛠️ Troubleshooting

$3

1. "No such module 'LiveActivitiesKit'"
- Ensure you added the Podfile target correctly
- Run npx cap sync after adding the Podfile entry

2. Live Activities not appearing
- Check that NSSupportsLiveActivities` is in Info.plist
- Verify App Groups are configured for both targets
- Ensure you're testing on iOS 16.2+ device

3. Dynamic Island not working
- Dynamic Island requires iPhone 14 Pro/Pro Max or newer
- Test regular Live Activities first

4. Build errors in Xcode
- Clean build folder (Cmd+Shift+K)
- Delete DerivedData
- Ensure Widget Extension target has correct settings

$3

- 📖 Check the example app for complete implementations
- 🐛 Report issues on GitHub
- 💬 Join discussions in the issues section

Maintainers

| Maintainer | GitHub | Social | LinkedIn |
| ---------------------- | ------------------------------------- | --------------------------------- | ------------------------------------------------------------------ |
| Luan Freitas (ludufre) | ludufre | @ludufre | Luan Freitas |