Anfänger

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihre AI-Werkzeug hinzufügen, indem Sie den folgenden Befehl ausführen:

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

Dann verwenden Sie den folgenden Vorschlag:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen plattform-spezifischen Anweisungen:

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

iOS-Einrichtung

Die Installation und Synchronisierung des Plugins erzeugt keine native Live Activity UI. ActivityKit erfordert eine Widget-Erweiterung, die eine Live Activity-Konfiguration registriert, bevor startActivity etwas angezeigt werden kann.

Erfordernisse

• Für beide Zielgruppen des App-Targets und des Widget-Extension-Targets verwenden Sie iOS 16.1 oder eine spätere Version.
• Testen Sie die App auf einem iOS-Gerät oder einem kompatiblen Simulator. Die Dynamic Island erscheint nur auf unterstützten Gerätemodellen; andere Geräte verwenden die Anzeige des Schlossbildschirms.
• Behalten Sie die kombinierten statischen und dynamischen ActivityKit-Daten unter 4 KB bei, wie von Apple gefordert.

1. Erstellen Sie eine Widget-Erweiterung

Öffnen Sie das native iOS-Projekt:

bunx cap open ios

Dann:

1. Wählen Sie Datei > Neu > Ziel.
2. Ein " Widget-Erweiterung.
3. Aktivieren Live-Aktivität einschließen.
4. Deaktivieren Konfigurationsabsicht einschließen es sei denn, die App benötigt auch eine konfigurierbare Widget.
5. Stellen Sie sicher, dass die generierte Erweiterung im Haupt-App-Ziel eingebettet ist.

Die Widget-Erweiterung muss einen " ActivityConfiguration und es in seinem " WidgetBundleanmelden. Sie muss alle erforderlichen Live-Aktivitätspräsentationen bereitstellen:

• Schutzschirm
• Dynamic Island erweitert
• Dynamic Island komprimiert führend und abschließend
• Dynamic Island minimal

Die Hinzufügung des Ziels allein ist nicht ausreichend. Die native App oder Plugin muss die ActivityKit-APIs request, update und end aufrufen. Die Erweiterung muss SwiftUI code enthalten, die das gleiche JSON-Layout dekodieren und rendern kann, das von diesen Aufrufen verwendet wird. Fügen Sie die von ActivityKit verwendeten Inhaltszustände in beide Haupt-App- und Widget-Erweiterungsziele ein. Der vom Xcode generierte Live-Aktivitäten-Template renderiert die vom Plugin übergebenen JSON-Layouts nicht automatisch; die Erweiterung benötigt auch einen kompatiblen native Layout-Renderer. ActivityAttributes 2. Live-Aktivitäten aktivieren

Abschnitt mit dem Titel „2. Live-Aktivitäten aktivieren“

Zur Zwischenablage kopieren Info.plist:

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

, fügt es Info.plist2 Unterstützt Live-Aktivitäten mit einem booleschen Wert von YES unter den Eigenschaften des Haupt-App-Targets für iOS anstatt.

3. Konfigurieren Sie die App-Gruppe für gemeinsam genutzte Bilder

Eine App-Gruppe ist nur erforderlich, wenn Sie saveImage, removeImage, listImages, oder cleanupImages. Die Erweiterung leitet den App-Gruppen-Bezeichner aus dem Haupt-App-Bundle-Bezeichner ab, wobei dieser im genauen Format verwendet wird:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Zum Beispiel muss eine App mit dem Bundle-Bezeichner com.example.delivery den folgenden App-Gruppen-Bezeichner verwenden:

group.com.example.delivery.liveactivities

In Xcode, fügen Sie der App-Gruppen Fähigkeit sowohl dem Hauptanwendungsziel als auch dem Widget-Erweiterungsziel hinzu, aktivieren Sie dann denselben Identifikator auf beiden Zielen.

Live-Aktivitäts-Erweiterungen können den Netzwerkzugriff nicht nutzen. Laden Sie remote Bilder in der Hauptanwendung herunter und speichern Sie sie in der gemeinsamen App-Gruppe, bevor Sie sie von einer Live-Aktivität aus referenzieren. Für eingebettete Bilder aktivieren Sie auch die Widget-Erweiterung in der Zielmitgliedschaft der Asset.

4. Konfigurieren Sie die tiefen Links

Bei Verwendung von behavior.widgetUrl oder einer Timerfolge tapUrlregistrieren Sie die passende URL-Scheme oder Universal Link in der Hauptanwendung. Für ein benutzerdefiniertes Scheme wie myapp://order/12345fügen Sie den Scheme unter den Info > URL-Typen Einstellungen des Hauptanwendungsziels hinzu.

5. Optional: Servergetriebene Updates aktivieren

Für lokale Updates, die vom App initiiert werden, sind Push-Nachrichten nicht erforderlich. Um von einem Server aus Live-Aktivitäten zu starten, zu aktualisieren oder zu beenden:

• Add the Fügen Sie der Push-Nachrichten
• Fähigkeit zum Haupt-App-Ziel hinzu.
• Ermitteln Sie die ActivityKit-Push-Tokens und senden Sie sie an den Server. liveactivity Senden Sie ActivityKit-Nachrichten über APNs mithilfe des
• Push-Typs. NSSupportsLiveActivitiesFrequentUpdates Fügen Sie Info.plist zum Haupt-App nur dann hinzu, wenn der Anwendungsfall häufige Push-Updates erfordert.

ActivityKit-Push-Tokens sind getrennt von Standard-Benachrichtigungsgeräte-Token. Die Aktivierung der Push-Nachrichten-Fähigkeit reicht allein nicht aus; servergetriebene Updates erfordern native Token-Verwaltung und einen APNs-Hintergrundprozess.

Native Setup-Checkliste

aktiviert ist. startActivityDas Widget-Extension ist eingebettet und registriert ein

• NSSupportsLiveActivities Die native ActivityKit-Implementierung und die Widget-Extension verwenden denselben
• Typ. ActivityConfiguration.
• Die App und die Widget-Extension-Deploymentsziele sind iOS 16.1 oder später. ActivityAttributes Live-Aktivitäten sind für die App in den iOS-Einstellungen aktiviert.
• Die entsprechende App-Gruppe ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Die App-Gruppe ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Die App-Gruppe ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das verwendet wird widgetUrl oder tapUrl wird registriert.

Import

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

API Übersicht

areActivitiesSupported

Überprüfen Sie, ob Live-Aktivitäten auf diesem Gerät unterstützt werden. Benötigt iOS 16.1+ und 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

Einen neuen Live Aktivitäten mit der angegebenen Layout und 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

Eine bestehende Live Aktivität 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

Eine Live Aktivität 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

Alle derzeit aktiven Live Aktivitäten abrufen.

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

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

saveImage

Speichern Sie ein Bild in dem gemeinsamen App-Gruppen-Container für die Verwendung in Live-Aktivitäten. Bilder müssen im gemeinsamen Container gespeichert werden, um von der Widget-Erweiterung zugänglich zu sein.

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

Entfernen Sie ein gespeichertes Bild aus dem gemeinsamen Container.

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

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

listImages

Auflisten Sie alle gespeicherten Bilder im gemeinsamen Container.

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

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

cleanupImages

Entfernen Sie alle gespeicherten Bilder aus dem gemeinsamen Container.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Starte eine Timersequenz für Workout/Sport. Auf iOS: Zeigt in der Live-Aktivität und im Dynamic Island Auf Android: Zeigt als Vordergrundbenachrichtigung mit Timer

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

Pausiere die Timersequenz.

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

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

resumeTimerSequence

Fortsetze eine pausierte Timersequenz.

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

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

stopTimerSequence

Beende und lösche die Timersequenz.

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

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

skipTimerStep

Zur nächsten Schrittfolge springen.

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

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

previousTimerStep

Zurück zur vorherigen Schrittfolge springen.

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

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

getTimerState

Ermitteln Sie den aktuellen Zustand einer Timerfolge.

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`);

Typenverweis

AreActivitiesSupportedResult

Ermitteln Sie den Zustand, ob Aktivitäten unterstützt werden.

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

StartActivityOptions

Optionen zum Starten einer Live-Aktivität.

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

Erfolg einer gestarteten Aktivität.

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

UpdateActivityOptions

Optionen zum Aktualisieren einer Live-Aktivität.

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

Optionen zum Beenden einer Live-Aktivität.

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

Ergebnis von getAllActivities.

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

SaveImageOptions

Optionen für das Speichern einer Bilddatei.

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

Ergebnis des Bildspeichers.

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

RemoveImageOptions

Optionen für das Löschen einer Bilddatei.

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

RemoveImageResult

Ergebnis der Entfernung eines Bildes.

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

ListImagesResult

Ergebnis der Auflistung von Bildern.

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

TimerSequenceOptions

Optionen für die Startsequenz eines Timers.

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;
}

Quelle der Wahrheit

This page is generated from the plugin’s src/definitions.tsRe-run the sync when the public API ändert sich upstream.

Fortfahren von Getting Started

Wenn Sie Getting Started verwenden um das Dashboard und __CAPGO_KEEP_0__-Operationen zu planen, verbinden Sie es mit Mit @API/__CAPGO_KEEP_1__-live-Aktivitäten zur nativen Fähigkeit in Mit @capgo/capacitor-live-Aktivitäten for the native capability in Using @capgo/capacitor-live-activities, zur Implementierungsdetails in API-Übersicht for the implementation detail in API Overview, Re-run the sync when the public __CAPGO_KEEP_0__ changes upstream. für die Implementierungsdetails in Einführung API Schlüssel für die Implementierungsdetails in API Schlüssel und Geräte für die Implementierungsdetails in Geräte.