Getting Started

Installieren

Sie können unser AI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem AI-Tool hinzu, indem Sie folgenden Befehl ausführen:

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

Verwenden Sie dann die folgende Anfrage:

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 die unten angegebenen plattform-spezifischen Anweisungen befolgen:

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

iOS-Einrichtung

Die Installation und Synchronisierung des Plugins erzeugt keine native Live-Aktivitäts-Oberfläche. ActivityKit erfordert eine Widget-Erweiterung, die eine Live-Aktivitäts-Konfiguration registriert, bevor sie etwas anzeigen kann. startActivity Kann alles anzeigen.

Requirements

• Verwenden Sie iOS 16.1 oder eine spätere Version für beide Zielgruppen, App-Target und Widget-Extension-Target.
• Testen Sie 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 auf dem Lock Screen.
• Halten Sie die kombinierten statischen und dynamischen ActivityKit-Daten unter 4 KB, 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 > Neues Ziel >.
2. Hinzufügen 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 in der Haupt-App-Ziel eingebettet ist.

Die Widget-Erweiterung muss einen ActivityConfiguration und es in seinem WidgetBundleregistrieren. Sie muss alle erforderlichen Live-Aktivitäten präsentieren:

• Bildschirmschoner
• Dynamische Insel erweitert
• Dynamische Insel kompakt führend und abschließend
• Dynamische Insel minimal

Adding the target alone is not sufficient. The native app or plugin must call ActivityKit’s request, update, and end APIs. The extension must contain SwiftUI code that can decode and render the same ActivityAttributes and content state used by those calls. Include shared ActivityKit models in both the main app and Widget Extension targets. The Xcode-generated Live Activity template does not automatically render the JSON layouts passed to this plugin; the extension also needs a compatible native layout renderer.

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

Fügen Sie die folgende Schlüssel zum Hauptanwendungsziel hinzu. Info.plist:

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

Wenn das Projekt seine Info.plist, add mit einem Boolean-Wert von Supports Live Activities YES unter der Hauptanwendungszieldaten für die benutzerdefinierte iOS-Zieldaten anstatt.

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

Eine App-Gruppe ist nur erforderlich, wenn Sie saveImage, removeImage, listImagesoder cleanupImagesDer Plugin extrahiert den App-Gruppen-Bezeichner aus dem Haupt-App-Bundle-Bezeichner in dieser genauen Format:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Beispiel: Eine App mit dem Bundle-Identifikator com.example.delivery muss verwenden:

group.com.example.delivery.liveactivities

In Xcode fügen Sie die App-Gruppen Fähigkeit, sowohl auf das Hauptanwendungsziel als auch auf das Widget-Erweiterungsziel anzuwenden, und dann dieselbe ID auf beiden Zielen aktivieren.

Live-Aktivitäts-Erweiterungen können nicht auf das Netzwerk zugreifen. Lade remote Bilder in der Hauptanwendung herunter und speichere sie im gemeinsamen App-Gruppen-Container, bevor du sie von einer Live-Aktivität referenzierst. Für gebundene Bilder aktiviere auch die Widget-Erweiterung in der Zielmitgliedschaft des Assets.

4. Konfiguration von Deep Links

Bei Verwendung behavior.widgetUrl oder einer Timersequenz 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 dem Haupt-App-Ziel ein. Info > URL-Typen settings.

5. Optional: Aktiviere Servergetriebene Updates

Push-Notifikationen sind nicht erforderlich für lokale Updates, die durch die App initiiert werden. Um Live-Aktivitäten zu starten, zu aktualisieren oder abzuschließen, verwenden Sie einen Server:

• Die Fernmeldenachrichten zu der Hauptanwendung hinzufügen.
• Erhalten Sie die ActivityKit-Push-Tokens und senden Sie sie an den Server.
• Senden Sie ActivityKit-Nachrichten über APNs mithilfe des liveactivity Fernmeldetyps.
• Add NSSupportsLiveActivitiesFrequentUpdates zur Hauptanwendung Info.plist nur dann, wenn der Anwendungszweck häufige Push-Updates erfordert.

ActivityKit push tokens are separate from standard user-notification device tokens. Enabling the Push Notifications capability alone is not sufficient; server-driven updates require native token handling and an APNs backend.

Setup-Checkliste für native Anwendungen

Bevor Sie anrufen startActivityprüfen Sie, ob

• NSSupportsLiveActivities für die Hauptzielgruppe aktiviert ist.
• Der Widget-Erweiterung ist eingebettet und registriert ein ActivityConfiguration.
• Die native ActivityKit-Implementierung und die Widget-Erweiterung verwenden den gleichen ActivityAttributes Typ.
• Die App- und Widget-Erweiterungszielgruppen sind iOS 16.1 oder später.
• Live-Aktivitäten sind für die App in den iOS-Einstellungen aktiviert.
• Die entsprechende App-Gruppe ist auf beiden Zielgruppen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das von widgetUrl oder tapUrl ist registriert.

Importieren

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

Starten Sie eine neue Live-Aktivität mit der angegebenen Layout- und Datenkonfiguration.

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

Ein bestehendes Live-Update 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

Ein Live-Update 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-Updates abrufen.

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

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

saveImage

Eine Bilddatei in den gemeinsamen App-Container speichern, um sie im Live-Update zu verwenden. Bilder müssen in den 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

Ein gespeichertes Bild aus dem gemeinsamen Container entfernen.

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

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

listImages

Alle gespeicherten Bilder im gemeinsamen Container auflisten.

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

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

cleanupImages

Alle gespeicherten Bilder aus dem gemeinsamen Container löschen.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Eine Timersequenz für Workouts/Sportarten starten. Bei iOS: Anzeigt sich im Live-Bildschirm und Dynamic Island Bei Android: Als Vordergrundbenachrichtigung 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

Die Timersequenz pausieren.

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

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

resumeTimerSequence

Eine pausierte Timersequenz wieder aufnehmen.

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

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

stopTimerSequence

Die Timersequenz stoppen und abblenden.

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

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

skipTimerStep

Zum nächsten Schritt in der Sequenz springen.

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

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

previousTimerStep

Zurück zur vorherigen Schrittfolge.

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

Typenreferenz

AreActivitiesSupportedResult

Erfolg der Überprüfung, 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 für das 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 des Starts einer Aktivität.

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

UpdateActivityOptions

Optionen für das 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 für das 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

Ergbnis von getAllActivities.

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

SaveImageOptions

Optionen fr die Bildspeicherung

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

Ergbnis der Bildspeicherung

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

RemoveImageOptions

Optionen fr die Bildentfernung

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

RemoveImageResult

Erfolg aus der Entfernung einer Bild.

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

ListImagesResult

Erfolg bei 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

Diese Seite wird aus dem Plugin generiert. src/definitions.tsRe-run die Synchronisation, wenn die öffentliche API sich im Hintergrund ändert.

Weitermachen von Getting Started

Wenn Sie Getting Started verwenden Getting Started um das Dashboard und die API-Operationen zu planen, verbinden Sie es mit Mit @capgo/capacitor-live-activities für die native Fähigkeit in Mit @capgo/capacitor-live-activities, API-Übersicht für die Implementierungsdetails in API-Übersicht, Einführung für die Implementierungsdetails in Einführung, API-Schlüssel zur Implementierungsdetail in API Schlüsseln und Geräte für die Implementierungsdetails in Geräten.