Erste Schritte
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-live-activities`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/live-activities/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
Installieren
Abschnitt „Installation“Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:
bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsNutze dann diesen Prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:
bun add @capgo/capacitor-live-activitiesbunx cap synciOS-Setup
Abschnitt mit dem Titel „iOS Setup“Installation und Synchronisierung des Plugins erzeugen nicht die native Live Activity UI. ActivityKit benötigt eine Widget Extension, die eine Live-Activity-Konfiguration registriert, bevor startActivity etwas anzeigen kann.
Anforderungen
Abschnitt „Voraussetzungen“- Verwende iOS 16.1 oder neuer für das App-Target und das Widget-Extension-Target.
- Teste auf einem iOS-Gerät oder einem kompatiblen Simulator. Die Dynamic Island erscheint nur auf unterstützten Gerätemodellen; andere Geräte nutzen die Darstellung auf dem Lock Screen.
- Halte die kombinierten statischen und dynamischen ActivityKit-Daten unter dem 4-KB-Limit von Apple.
1. Erstelle eine Widget Extension
Abschnitt: „1. Widget Extension erstellen“Öffne das native iOS-Projekt:
bunx cap open iosDanach:
- Wähle Datei > Neu > Target.
- Füge einen Widget-Extension.
- Aktivieren Live Activity einschließen.
- Deaktivieren Configuration Intent einbinden es sei denn, die App benötigt auch ein konfigurierbares Widget.
- Stellen Sie sicher, dass die generierte Extension im Haupt-App-Target eingebettet ist.
Die Widget Extension muss einen ActivityConfiguration und ihn darin registrieren WidgetBundle. Sie muss jede erforderliche Live-Activity-Darstellung bereitstellen:
- Sperrbildschirm
- Dynamic Island (erweitert)
- Dynamic Island (kompakt, leading und trailing)
- Dynamic Island (minimal)
Das Hinzufügen des Targets allein reicht nicht aus. Die native App oder das Plugin muss die request-, update- und end-APIs von ActivityKit aufrufen. Die Extension muss SwiftUI code enthalten, die dieselben Daten dekodieren und rendern kann. ActivityAttributes und den Content State, der von diesen Aufrufen verwendet wird. Integriere gemeinsame ActivityKit-Modelle sowohl in das Haupt-App- als auch in das Widget-Extension-Target. Das von Xcode generierte Live-Activity-Template rendert die an dieses Plugin übergebenen JSON-Layouts nicht automatisch; die Extension braucht außerdem einen kompatiblen nativen Layout-Renderer.
2. Live Activities aktivieren
Abschnitt mit dem Titel „2. Live Activities aktivieren“Füge den folgenden Schlüssel zum Target der Haupt-App hinzu Info.plist:
<key>NSSupportsLiveActivities</key><true/>Wenn das Projekt seine Info.plist, füge Unterstützt Live Activities mit einem booleschen Wert von YES stattdessen unter den benutzerdefinierten iOS-Target-Eigenschaften des Haupt-App-Targets ein.
3. App Group für geteilte Bilder konfigurieren
Abschnitt mit dem Titel „3. App-Gruppe für geteilte Bilder konfigurieren“Eine App Group ist nur erforderlich, wenn Sie saveImage, removeImage, listImages, oder cleanupImages. Das Plugin leitet den App Group Identifier aus dem Bundle Identifier der Haupt-App in genau diesem Format ab:
group.<MAIN_APP_BUNDLE_ID>.liveactivitiesZum Beispiel eine App mit Bundle Identifier com.example.delivery muss verwenden:
group.com.example.delivery.liveactivitiesFüge in Xcode die App-Gruppen füge die Capability sowohl dem Haupt-App-Target als auch dem Widget Extension Target hinzu und aktiviere anschließend denselben Identifier für beide Targets.
Live Activity Extensions haben keinen Netzwerkzugriff. Lade Remote-Bilder in der Haupt-App herunter und speichere sie im gemeinsamen App-Group-Speicher, bevor du sie in einer Live Activity referenzierst. Bei gebündelten Bildern aktiviere außerdem die Widget Extension in der Target Membership des Assets.
4. Deep Links konfigurieren
Abschnitt mit dem Titel „4. Deep Links konfigurieren“Bei Verwendung von behavior.widgetUrl oder eine Timer-Sequenz tapUrl, registriere das passende URL-Schema oder den Universal Link in der Haupt-App. Für ein benutzerdefiniertes Schema wie myapp://order/12345, füge das Schema unter dem Haupt-App-Target hinzu: Info > URL-Typen Einstellungen.
5. Optional: Server-gesteuerte Updates aktivieren
Abschnitt mit dem Titel „5. Optional: Server-gesteuerte Updates aktivieren“Push-Benachrichtigungen sind für lokale Updates, die von der App ausgelöst werden, nicht erforderlich. Um Live Activities von einem Server aus zu starten, zu aktualisieren oder zu beenden:
- Füge den Push-Benachrichtigungen Capability zum Haupt-App-Target hinzufügen.
- ActivityKit-Push-Tokens abrufen und an den Server senden.
- ActivityKit-Benachrichtigungen über APNs mit dem
liveactivityPush-Typ senden. - Füge
NSSupportsLiveActivitiesFrequentUpdateszum Haupt-App-TargetInfo.plistnur, wenn der Use Case häufige Push-Updates erfordert.
ActivityKit-Push-Tokens sind von den Standard-Gerätetokens für Benachrichtigungen getrennt. Das Aktivieren der Push-Benachrichtigungs-Capability allein reicht nicht aus; servergesteuerte Updates erfordern native Token-Verarbeitung und einen APNs-Backend.
Checkliste für das Native Setup
Abschnitt mit dem Titel „Native Setup Checklist“Bevor du aufrufst startActivityaufrufst, sicherstellen, dass:
NSSupportsLiveActivitiesist im Haupt-App-Target aktiviert.- Die Widget-Erweiterung ist eingebettet und registriert eine
ActivityConfiguration. - Die native ActivityKit-Implementierung und die Widget-Erweiterung verwenden denselben
ActivityAttributesTyp. - Die Deployment-Ziele für die App und die Widget-Erweiterung sind iOS 16.1 oder höher.
- Live Activities sind in den iOS-Einstellungen für die App aktiviert.
- Die passende App Group ist auf beiden Zielen aktiviert, wenn geteilte Bilder verwendet werden.
- Jedes benutzerdefinierte URL-Schema, das von
widgetUrlodertapUrlverwendet wird, ist registriert.
Importieren
Abschnitt mit dem Titel „Import“import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';Quickstart
Abschnitt „Quick start“import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();if (supported) { console.log('Live Activities are supported!');} else { console.log('Not supported:', reason);}Beispiel: startActivity
Abschnitt mit dem Titel „Beispiel: startActivity“import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { activityId } = await CapgoLiveActivities.startActivity({ layout: { type: 'container', direction: 'horizontal', children: [ { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' }, { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' } ] }, dynamicIslandLayout: { expanded: { leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' }, trailing: { type: 'text', content: '{{eta}}' }, center: { type: 'text', content: '{{status}}' }, bottom: { type: 'progress', value: 'progress' } }, compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' }, compactTrailing: { type: 'text', content: '{{eta}}' }, minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' } }, data: { orderNumber: '12345', status: 'On the way', eta: '10 min', progress: 0.6 }});console.log('Started activity:', activityId);Beispiel: updateActivity
Abschnitt mit dem Titel „Beispiel: updateActivity“import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.updateActivity({ activityId: 'abc123', data: { status: 'Arrived!', eta: 'Now', progress: 1.0 }, alertConfiguration: { title: 'Delivery Update', body: 'Your order has arrived!' }});Häufige Stolperfallen
Abschnitt „Häufige Fallstricke“- Listener: Handles beim Unmounten von Screens entfernen.
- Nativer Sync: ausführen
bunx cap syncnach Plugin-Upgrades. - Single Source of Truth: Vertrauen
src/definitions.tsim GitHub Repo.
API Übersicht
Abschnitt „API Übersicht“areActivitiesSupported
Abschnitt mit dem Titel „areActivitiesSupported“Prüfen, ob Live Activities auf diesem Gerät unterstützt werden. Erfordert iOS 16.1+ und entsprechende Geräteunterstützung.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();if (supported) { console.log('Live Activities are supported!');} else { console.log('Not supported:', reason);}startActivity
Abschnitt „startActivity“Eine neue Live Activity mit dem angegebenen Layout und den angegebenen Daten starten.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { activityId } = await CapgoLiveActivities.startActivity({ layout: { type: 'container', direction: 'horizontal', children: [ { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' }, { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' } ] }, dynamicIslandLayout: { expanded: { leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' }, trailing: { type: 'text', content: '{{eta}}' }, center: { type: 'text', content: '{{status}}' }, bottom: { type: 'progress', value: 'progress' } }, compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' }, compactTrailing: { type: 'text', content: '{{eta}}' }, minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' } }, data: { orderNumber: '12345', status: 'On the way', eta: '10 min', progress: 0.6 }});console.log('Started activity:', activityId);updateActivity
Abschnitt „updateActivity“Eine bestehende Live Activity mit neuen Daten aktualisieren.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.updateActivity({ activityId: 'abc123', data: { status: 'Arrived!', eta: 'Now', progress: 1.0 }, alertConfiguration: { title: 'Delivery Update', body: 'Your order has arrived!' }});endActivity
Abschnitt „endActivity“Eine Live Activity beenden.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.endActivity({ activityId: 'abc123', data: { status: 'Delivered' }, dismissalPolicy: 'after', dismissAfter: Date.now() + 3600000 // 1 hour from now});getAllActivities
Abschnitt „getAllActivities“Alle aktuell aktiven Live Activities abrufen.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { activities } = await CapgoLiveActivities.getAllActivities();activities.forEach(activity => { console.log(`Activity ${activity.activityId}: ${activity.state}`);});saveImage
Abschnitt „saveImage“Speichert ein Bild im gemeinsamen App-Group-Container für die Verwendung in Live Activities. Bilder müssen im gemeinsamen Container gespeichert werden, damit die Widget Extension darauf zugreifen kann.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { success, imageName } = await CapgoLiveActivities.saveImage({ imageData: 'base64EncodedImageData...', name: 'product-image', compressionQuality: 0.8});// Use in layout with: { type: 'image', source: 'saved', value: imageName }removeImage
Abschnitt „removeImage“Entfernt ein gespeichertes Bild aus dem gemeinsamen Container.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });listImages
Abschnitt „listImages“Listet alle im gemeinsamen Container gespeicherten Bilder auf.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { images } = await CapgoLiveActivities.listImages();console.log('Saved images:', images);cleanupImages
Abschnitt „cleanupImages“Entfernt alle gespeicherten Bilder aus dem gemeinsamen Container.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.cleanupImages();startTimerSequence
Abschnitt „startTimerSequence“Starte eine Timer-Sequenz für Workouts/Sport. Auf iOS: Wird in der Live Activity und der Dynamic Island angezeigt Auf Android: Wird als Foreground-Notification mit Timer angezeigt
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { sequenceId } = await CapgoLiveActivities.startTimerSequence({ title: 'HIIT Workout', steps: [ { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' }, { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' }, { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' }, { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' }, { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' }, { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' }, ], loop: true, loopCount: 3, soundEnabled: true, vibrateEnabled: true, countdownBeeps: true, tapUrl: 'myapp://workout/hiit'});pauseTimerSequence
Abschnitt „pauseTimerSequence“Pausiere die Timer-Sequenz.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });resumeTimerSequence
Abschnitt „resumeTimerSequence“Setze eine pausierte Timer-Sequenz fort.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });stopTimerSequence
Abschnitt „stopTimerSequence“Stoppe und schließe die Timer-Sequenz.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });skipTimerStep
Abschnitt mit dem Titel “skipTimerStep”Zum nächsten Schritt in der Sequenz springen.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });previousTimerStep
Abschnitt mit dem Titel “previousTimerStep”Gehe zum vorherigen Schritt der Sequenz zurück.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });getTimerState
Abschnitt mit dem Titel “getTimerState”Rufe den aktuellen Status einer Timer-Sequenz ab.
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);console.log(`Time remaining: ${state.remainingSeconds}s`);Typreferenz
Abschnitt mit dem Titel „Typreferenz“AreActivitiesSupportedResult
Abschnitt mit dem Titel „AreActivitiesSupportedResult“Ergebnis der Prüfung, ob Activities unterstützt werden.
export interface AreActivitiesSupportedResult { /** Whether Live Activities are supported on this device */ supported: boolean; /** Reason if not supported */ reason?: string;}StartActivityOptions
Abschnitt mit dem Titel „StartActivityOptions“Optionen zum Starten einer Live Activity.
export interface StartActivityOptions { /** Main activity layout (lock screen widget) */ layout: ActivityLayout; /** Dynamic Island layout configuration */ dynamicIslandLayout: DynamicIslandLayout; /** Activity behavior settings */ behavior?: LiveActivitiesBehavior; /** Dynamic data for the activity */ data: Record<string, unknown>; /** Stale date timestamp (activity becomes stale after this) */ staleDate?: number; /** Relevance score for activity ordering (0-100) */ relevanceScore?: number;}StartActivityResult
Abschnitt mit dem Titel „StartActivityResult“Ergebnis beim Starten einer Activity.
export interface StartActivityResult { /** Unique activity identifier */ activityId: string;}UpdateActivityOptions
Abschnitt mit dem Titel „UpdateActivityOptions“Optionen zum Aktualisieren einer Live Activity.
export interface UpdateActivityOptions { /** Activity ID to update */ activityId: string; /** Updated data */ data: Record<string, unknown>; /** Optional alert to show with update */ alertConfiguration?: ActivityAlertConfiguration; /** Updated stale date */ staleDate?: number; /** Updated relevance score */ relevanceScore?: number;}EndActivityOptions
Abschnitt mit dem Titel „EndActivityOptions“Optionen zum Beenden einer Live Activity.
export interface EndActivityOptions { /** Activity ID to end */ activityId: string; /** Final data to display */ data?: Record<string, unknown>; /** Dismissal policy */ dismissalPolicy?: 'immediate' | 'default' | 'after'; /** Dismiss after timestamp (when dismissalPolicy is 'after') */ dismissAfter?: number;}GetAllActivitiesResult
Abschnitt mit dem Titel „GetAllActivitiesResult“Ergebnis von getAllActivities.
export interface GetAllActivitiesResult { /** List of activities */ activities: ActivityInfo[];}SaveImageOptions
Abschnitt mit dem Titel „SaveImageOptions“Optionen zum Speichern eines Bildes.
export interface SaveImageOptions { /** Base64 encoded image data */ imageData: string; /** Name to save the image as */ name: string; /** JPEG compression quality (0-1, default 0.8) */ compressionQuality?: number;}SaveImageResult
Abschnitt mit dem Titel „SaveImageResult“Ergebnis des Speicherns eines Bildes.
export interface SaveImageResult { /** Whether the save was successful */ success: boolean; /** Saved image name */ imageName: string;}RemoveImageOptions
Abschnitt mit dem Titel „RemoveImageOptions“Optionen zum Entfernen eines Bildes.
export interface RemoveImageOptions { /** Name of the image to remove */ name: string;}RemoveImageResult
Abschnitt mit dem Titel „RemoveImageResult“Ergebnis des Bildentfernens.
export interface RemoveImageResult { /** Whether the removal was successful */ success: boolean;}ListImagesResult
Abschnitt mit dem Titel „ListImagesResult“Ergebnis der Bildliste.
export interface ListImagesResult { /** List of saved image names */ images: string[];}TimerSequenceOptions
Abschnitt mit dem Titel „TimerSequenceOptions“Optionen zum Starten einer Timer-Sequenz.
export interface TimerSequenceOptions { /** Array of steps in the sequence */ steps: TimerStep[]; /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */ title?: string; /** Whether to loop the sequence when complete */ loop?: boolean; /** Number of times to loop (if loop is true, 0 means infinite) */ loopCount?: number; /** Play sound on step change (default: true) */ soundEnabled?: boolean; /** Vibrate on step change (default: true) */ vibrateEnabled?: boolean; /** Play countdown beeps in last 3 seconds (default: true) */ countdownBeeps?: boolean; /** Deep link URL when tapping the notification/activity */ tapUrl?: string; /** Keep screen on during timer (Android only, default: false) */ keepScreenOn?: boolean;}Source of Truth
Abschnitt mit dem Titel „Source of Truth“Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.
Weiter geht's nach Getting Started
Abschnitt: „Weiter geht’s mit Getting Started“Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.