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 Ihrer KI-Tool mithilfe der folgenden Befehl hinzu:

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 eine 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 erzeugen keine native Live Activity-Oberfläche. ActivityKit erfordert eine Widget-Erweiterung, die eine Live Activity-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.
• Halten Sie die kombinierten statischen und dynamischen ActivityKit-Daten unter 4 KB, wie es Apple vorschreibt.
• Copy to clipboard

1. Ein Widget-Extension erstellen

Öffnen Sie das native iOS-Projekt:

bunx cap open ios

Dann:

1. Auswählen Datei > Neues Ziel >.
2. Ein Widget-Extension hinzufügen Einrichten.
3. Lebendige Aktivität einschließen Include Live Activity.
4. Deaktivieren Konfigurationsabsicht einschließen es sei denn, die App benötigt auch einen konfigurierbaren Widget.
5. Stellen Sie sicher, dass die generierte Erweiterung im Hauptanwendungsziel eingebettet ist.

Die Widget-Erweiterung muss einen ActivityConfiguration und es in seinem WidgetBundlemüssen alle erforderlichen Live-Aktivitätspräsentationen bereitstellen:

• Bildschirm mit verriegelter Schublade
• Erweiterte Dynamic Island
• Kompakte Dynamic Island führend und führend
• Minimal Dynamic Island

Die Hinzufügung des Ziels allein ist nicht ausreichend. Die native App oder Plugin müssen die APIs von ActivityKit aufrufen, aktualisieren und beenden. Die Erweiterung muss SwiftUI code enthalten, die die gleichen Daten dekodieren und rendern kann. ActivityAttributes und den Inhalt des Zustands, der von diesen Aufrufen verwendet wird. Fügen Sie die gemeinsamen ActivityKit-Modelle sowohl in der Hauptanwendung als auch in der Widget-Erweiterungsziel ein. Das vom Xcode generierte Live-Aktivitäten-Template renderiert die von diesem Plugin übergebenen JSON-Layouts nicht automatisch; die Erweiterung benötigt auch einen kompatiblen nativen Layout-Renderer.

2. Live-Aktivitäten aktivieren

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

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

Wenn das Projekt seinen Info.plist, fügen Sie hinzu Live-Aktivitäten unterstützen mit einem Boolean-Wert von YES unter den Hauptanwendungsziel-Eigenschaften für das benutzerdefinierte iOS-Ziel anstatt.

3. Konfigurieren Sie das App-Gruppen-ziel für gemeinsame Bilder

Eine App-Gruppe ist nur erforderlich, wenn Sie saveImage, removeImage, listImages oder cleanupImages verwenden. Die Plugin extrahiert die App-Gruppen-Identifikator aus dem Haupt-App-Bundle-Identifikator in genau dieser Format:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

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

group.com.example.delivery.liveactivities

In Xcode fügen Sie der Haupt-App-Ziel- und der Widget-Erweiterungsziel-App-Gruppen-Fähigkeit hinzu, aktivieren Sie dann denselben Identifikator auf beiden Zielen. Live-Aktivitäten-Extensions können nicht auf das Netzwerk zugreifen. Laden Sie remote Bilder im Haupt-App herunter und speichern Sie sie in der gemeinsamen App-Gruppe, bevor Sie sie von einer Live-Aktivität referenzieren. Für eingebettete Bilder aktivieren Sie auch die Widget-Erweiterung in der Zielmitgliedschaft der Ressource. 4. Konfigurieren Sie tiefgreifende Links

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

Wenn Sie Deep Links verwenden behavior.widgetUrl oder eine Timerfolge tapUrlregistrieren Sie die entsprechende URL-Scheme oder Universal Link im Haupt-App. myapp://order/12345Für ein benutzerdefiniertes Scheme wie fügen Sie den Scheme unter den Haupt-App-Target’s Info > URL-Typen

Einstellungen.

Abschnitt mit dem Titel „5. Optional: Aktivieren Sie Servergetriebene Updates“

• Push-Benachrichtigungen sind nicht erforderlich für lokale Updates, die durch die App initiiert werden. Um Live-Aktivitäten von einem Server zu starten, zu aktualisieren oder zu beenden: Hinzufügen der Fähigkeit zur Hauptanwendung zugreifen.
• Erhalten Sie ActivityKit-Push-Tokens und senden Sie sie an den Server.
• Senden Sie ActivityKit-Benachrichtigungen über APNs mithilfe des liveactivity Push-Typs.
• Hinzufügen NSSupportsLiveActivitiesFrequentUpdates zur Hauptanwendung Info.plist nur dann, wenn der Use Case häufige Push-Updates erfordert.

ActivityKit-Push-Tokens sind getrennt von Standard-Benachrichtigungs-Geräte-Tokens. Die Aktivierung der Push-Benachrichtigungsfähigkeit allein ist nicht ausreichend; servergetriebene Updates erfordern native Token-Verwaltung und einen APNs-Hintergrund.

Native Setup-Checkliste

Bevor Sie startActivity, stellen Sie sicher, dass:

• NSSupportsLiveActivities ist auf dem Hauptziel der Anwendung aktiviert.
• Die Widget-Erweiterung ist eingebettet und registriert einen ActivityConfiguration.
• Die native ActivityKit-Implementierung und die Widget-Erweiterung verwenden den gleichen ActivityAttributes Typ.
• Die Anwendung und die Widget-Erweiterung werden auf iOS 16.1 oder später bereitgestellt.
• Live-Aktivitäten sind für die Anwendung in den iOS-Einstellungen aktiviert.
• Die passende App-Gruppe ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das von widgetUrl oder tapUrl registriert ist.

Import

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

API Übersicht

areActivitiesSupported

Überprüfen, 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

Ein 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

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-Gruppen-Container speichern, um es in Live-Aktivitäten 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 in der 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 entfernen.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

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

Die Timersequenz pausieren.

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

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

resumeTimerSequence

Eine angehaltene Timersequenz wiederherstellen.

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

Zur nächsten Schritt in der Sequenz springen.

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

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

previousTimerStep

Zum 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 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 das Ergebnis 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

Ergebnis der Aktivitätsstart.

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

UpdateActivityOptions

Optionen zur Aktualisierung 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

Erfolg der Bilddatei-Speicherung.

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

Erfolg des Bilddatei-Löschens.

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

Optionen für die Startzeit einer 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 von dem Plugin generiert. src/definitions.ts. Wenn sich die öffentliche API im Hintergrund ändert,

Weitermachen von Getting Started

Wenn Sie diese verwenden Einstieg um das Dashboard und die API-Operationen zu planen und es mit Mit @capgo/capacitor-live-Activities zu verwenden 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.