Einstieg

Installieren

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

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

Verwenden Sie dann 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 die darunter 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 Anforderungen

Abschnitt mit dem Titel “Anforderungen”

• 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 auf dem Schutzschirm.
• Stellen Sie sicher, dass die kombinierte statische und dynamische ActivityKit-Daten unter Apple’s 4 KB-Grenze liegen.
• 1. Erstellen Sie eine Widget-Erweiterung

Abschnitt mit dem Titel “1. Erstellen Sie eine Widget-Erweiterung”

Befehlszeichenfenster

bunx cap open ios

Dann:

1. Auswählen Datei > Neues > Ziel.
2. Hinzufügen 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 Hauptziel der App eingebettet ist.

Die Widget-Erweiterung muss einen ActivityConfiguration und registriere es in seinem WidgetBundle. Sie muss alle erforderlichen Live-Aktivitätsdarstellungen bereitstellen:

• Lock-Screen
• Dynamic Island erweitert
• Dynamic Island kompakt führend und abschließend
• Dynamic Island minimal

Hinzufügen 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 die gleichen ActivityAttributes und Inhaltszustand wie die Aufrufe decodieren und rendern können. Fügen Sie die gemeinsamen ActivityKit-Modelle in beide Haupt-App- und Widget-Erweiterung-Ziele ein. Das von Xcode generierte Live-Aktivitäts-Template renderiert die JSON-Layouts, die an diesen Plugin übergeben werden, nicht automatisch; Die Erweiterung benötigt auch einen kompatiblen native Layout-Renderer.

2. Live-Aktivitäten aktivieren

Fügen Sie die folgende Schlüssel zum Hauptziel der App hinzu Info.plist:

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

Wenn das Projekt seinen eigenen Info.plist, fügen Sie Unterstützt Live-Aktivitäten mit einem Boolean-Wert von YES unter den benutzerdefinierten iOS-Zielpunkteigenschaften des Hauptanwendungsziels an.

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

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

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Beispielweise muss eine App mit der Paket-Identifizierer com.example.delivery muss folgendes verwenden:

group.com.example.delivery.liveactivities

In Xcode fügen Sie der Hauptanwendung und der Widget-Erweiterung die App-Gruppen Fähigkeit hinzu, dann aktivieren Sie die gleiche Identifizierer auf beiden Ziele.

Live-Aktivitäten-Extensions können nicht auf das Netzwerk zugreifen. Laden Sie Remote-Bilder in der Hauptanwendung herunter und speichern Sie sie im gemeinsamen App-Gruppen vor, bevor Sie sie von einer Live-Aktivität aus referenzieren. Für gebundene Bilder aktivieren Sie auch die Widget-Erweiterung in der Zielmitgliedschaft der Asset.

4. Konfigurieren Sie die tiefen Links

Wenn Sie behavior.widgetUrl oder eine Timerfolge tapUrlverwenden, registrieren Sie die entsprechende URL-Scheme oder Universal Link in der Hauptanwendung. Für einen benutzerdefinierten Scheme wie myapp://order/12345, fügen Sie dem Hauptziel der Anwendung den Scheme hinzu. Info > URL-Typen Einstellungen.

5. Optional: Aktivieren Sie Servergetriebene Updates

Push-Benachrichtigungen sind für lokale Updates, die durch die Anwendung initiiert werden, nicht erforderlich. Um Live-Aktivitäten zu starten, zu aktualisieren oder zu beenden, senden Sie die folgenden Anfragen an den Server:

• Fügen Sie dem Hauptziel der Anwendung die Fähigkeit hinzu. Erhalten Sie die ActivityKit-Push-Tokens und senden Sie sie an den Server.
• Senden Sie ActivityKit-Benachrichtigungen über APNs mithilfe des
• Push-Typs. liveactivity Info > URL-Typen
• Hinzufügen NSSupportsLiveActivitiesFrequentUpdates zur Hauptanwendung Info.plist nur dann, wenn der Anwendungsfall häufige Push-Updates erfordert.

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

Native Setup-Checkliste

Bevor Sie startActivity, überprüfen Sie, dass:

• NSSupportsLiveActivities aktiviert ist auf der Hauptanwendungsziel.
• Das Widget-Extension ist eingebettet und registriert ein ActivityConfiguration.
• Die native ActivityKit-Implementierung und die Widget-Extension verwenden den gleichen ActivityAttributes Typ.
• Die App und die Widget-Erweiterung werden auf iOS 16.1 oder später bereitgestellt.
• Live-Aktivitäten sind für die App in den iOS-Einstellungen aktiviert.
• Das entsprechende App-Gruppen-Feature ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das von widgetUrl oder tapUrl Sind Sie bereits mit einer unserer Lösungen wie Appflow oder Capawesome vertraut?

ist registriert.

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

API Overview

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 Daten.

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

Aktualisieren Sie eine bestehende Live-Aktivität mit neuen Daten.

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

Beenden Sie eine Live-Aktivität.

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

Ein Bild in den gemeinsamen App-Gruppencontainer speichern, um es in Live-Aktivitäten zu verwenden. Bilder müssen in den gemeinsamen Container gespeichert werden, um von der Widget-Erweiterung zugreifbar 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 in dem gemeinsamen Container auflisten.

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 geteilten Container.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Starten Sie eine Timersequenz für Workouts/Sport. Bei iOS: Zeigt sich in der Live-Aktivität und im Dynamic Island Bei Android: Zeigt sich 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

Pausieren Sie die Timersequenz.

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

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

resumeTimerSequence

Fortsetzen Sie eine pausierte Timersequenz.

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

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

stopTimerSequence

Stoppen und die Timersequenz abbrechen.

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

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

skipTimerStep

Zur nächsten Schritt in der Sequenz springen.

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

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

previousTimerStep

Zur vorherigen Schritt in der Sequenz zurückkehren.

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

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

getTimerState

Ermitteln Sie den aktuellen Zustand einer Timersequenz.

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

Ergbnis 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

Ergbnis des Startens 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 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

Ergbnis von getAllActivities.

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

SaveImageOptions

Optionen zum 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

Ergbnis des Speicherns einer Bilddatei.

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

RemoveImageOptions

Einstellungen zur Entfernung eines Bildes.

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

RemoveImageResult

Ergebnis der Bildentfernung.

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

ListImagesResult

Ergebnis der Bildauflistung.

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

TimerSequenceOptions

Einstellungen zur Start eines Timersequenz.

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 Synchronisierung, wenn die öffentliche API upstream geändert wird.

Weitergehen von Getting Started

Wenn Sie das 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 für die Implementierungsdetails in API Schlüssel und Geräte für die Implementierungsdetails in Geräte.