Anleitung

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 verwenden:

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

Verwenden Sie dann den folgenden Prompt:

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 Plattform-spezifischen Anweisungen unten befolgen:

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

iOS-Einrichtung

Installieren und synchronisieren Sie das Plugin, um die native Live Activity UI nicht zu erstellen. ActivityKit erfordert eine Widget-Erweiterung, die eine Live Activity-Konfiguration registriert, bevor sie etwas anzeigen kann. startActivity Kann nichts anzeigen.

Anforderungen

• Verwenden Sie für beide Zielgruppen (App-Zielgruppe und Widget-Erweiterungszielgruppe) iOS 16.1 oder eine spätere Version.
• 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 Schutzschirm.
• Behalten Sie die kombinierte statische und dynamische ActivityKit-Daten unter Apple’s 4 KB-Grenze.

1. Erstellen Sie eine Widget-Erweiterung

Öffnen Sie das native iOS-Projekt:

bunx cap open ios

Dann:

1. Wählen Sie Datei > Neuanlegen > Ziel.
2. Hinzufügen eines Widget-Erweiterung.
3. Aktivieren Sie Live-Aktivität einschließen.
4. Deaktivieren Sie 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. Es muss alle erforderlichen Live-Aktivitätspräsentationen liefern:

• Lock Screen
• Dynamic Island erweitert
• Dynamic Island kompakt führend und führend
• Dynamic Island minimal

Hinzufügen des Ziels allein ist nicht ausreichend. Die native App oder Plugin muss die ActivityKit-APIs anfordern, aktualisieren und beenden. Die Erweiterung muss SwiftUI code enthalten, die die gleichen JSON-Layouts dekodieren und rendern kann, die von diesen Aufrufen verwendet werden. Fügen Sie die gemeinsamen ActivityKit-Modelle sowohl in der Haupt-App- als auch in der Widget-Erweiterungsziel ein. Das von Xcode generierte Live-Aktivitätsvorlage renderiert die JSON-Layouts nicht automatisch, die an diesen Plugin übergeben werden; 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“

Zwischenablage kopieren Info.plist:

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

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

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

Eine App-Gruppe ist nur erforderlich, wenn Sie saveImage, removeImage, listImagesoder cleanupImagesverwenden. Der Plugin bestimmt den App-Gruppenbezeichner aus dem Hauptanwendungs-Bundle-Identifier mithilfe dieses genauen Formats:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Beispiel: Eine App mit dem Bundle-Identifier com.example.delivery muss verwendet werden:

group.com.example.delivery.liveactivities

In Xcode, fügen Sie der App-Gruppen Fähigkeit zu beiden Hauptanwendungszielen und dem Widget-Erweiterungsziel hinzu, und aktivieren Sie dann denselben Identifikator auf beiden Zielen.

Live-Aktivitäts-Erweiterungen können nicht auf das Netzwerk zugreifen. 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 Zielzugehörigkeit der Asset.

4. Konfigurieren Sie tiefe Links

Wenn Sie behavior.widgetUrl oder eine Timersequenz verwenden tapUrl, registrieren Sie die entsprechende URL-Scheme oder Universal-Link in der Hauptanwendung. Für einen benutzerdefinierten Scheme wie myapp://order/12345, fügen Sie den Scheme unter dem Hauptanwendungsziel Info > URL-Typen Einstellungen.

5. Optional: Aktivitäten von Server aus aktivieren

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

• Die Fähigkeit zur Hinzufügung von Fähigkeit zur Hinzufügung von Fähigkeit zur Hinzufügung von
• Fähigkeit zur Hinzufügung von
• Fähigkeit zur Hinzufügung von liveactivity Fähigkeit zur Hinzufügung von
• Fähigkeit zur Hinzufügung von NSSupportsLiveActivitiesFrequentUpdates zur Hauptanwendung Info.plist nur wenn der Fall häufige Push-Updates erfordert.

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

Übersichtliche Setup-Checkliste

Bevor Sie aufrufen startActivitystellen Sie sicher, dass

• NSSupportsLiveActivities aktiviert ist auf dem Ziel der Hauptanwendung.
• Der Widget-Erweiterung ist eingebettet und registriert ein ActivityConfiguration.
• Die native ActivityKit-Implementierung und die Widget-Erweiterung verwenden denselben ActivityAttributes Typ.
• Die App- und Widget-Erweiterung-Zielsysteme sind iOS 16.1 oder später.
• Live Activities sind für die App in den iOS-Einstellungen aktiviert.
• Die entsprechende App-Gruppe ist auf beiden Zielen aktiviert, wenn gemeinsame Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das von widgetUrl oder tapUrl oder

ist registriert.

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

API Overview

areActivitiesSupported

Abschnitt mit dem Titel ‘areActivitiesSupported’

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

Ermitteln Sie alle derzeit aktiven Live-Aktivitäten.

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 im 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

Liste aller 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

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

Beenden und die Timersequenz abblenden.

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 vorherigen Schrittfolge 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

Ergibtum 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 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

Ergibtum des Startens einer 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 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

Ergebnis des Bildspeicherns.

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

RemoveImageOptions

Optionen zum Entfernen einer Bilddatei

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

RemoveImageResult

Ergbnis der Entfernung einer Bilddatei

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

ListImagesResult

Ergbnis der Auflistung von Bilddateien

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

TimerSequenceOptions

Optionen zum Starten 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 wurde aus dem Plugin generiert. src/definitions.ts. Wenn sich die öffentliche API im Hintergrund ändert, führen Sie den Sync erneut durch.

Fortsetzen von Getting Started

Wenn Sie das Plugin 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.