Anleitung

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten zu Ihrem AI-Tool hinzu, indem Sie die folgende 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 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-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”

Befehlszeile

bunx cap open ios

Dann:

1. Auswählen Datei > Neu > 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.

Der Widget-Erweiterung muss einen ActivityConfiguration und registriere es in seinem WidgetBundle. Es muss alle erforderlichen Live-Aktivitätspräsentationen bereitstellen:

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

Hinzufügen des Ziels allein ist nicht ausreichend. Die native App oder Plugin muss die Anfrage, Aktualisierung und Beendigung von ActivityKit aufrufen. Der Erweiterung muss SwiftUI code enthalten, die die gleichen ActivityAttributes und Inhaltszustand wie die Aufrufe dekodieren und rendern können. Fügen Sie die gemeinsamen ActivityKit-Modelle sowohl in der Haupt-App- als auch in der Widget-Erweiterung-Ziel ein. Das von Xcode generierte Live-Aktivitätsvorlage stellt die JSON-Layouts, die an diesen Plugin übergeben werden, nicht automatisch dar; der Erweiterung ist auch ein kompatibles natives Layout-Renderer erforderlich.

2. Live-Aktivitäten aktivieren

Fügen Sie die folgende Schlüssel zum Haupt-App-Ziel Info.plist:

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

Wenn das Projekt seinen Info.plistaddieren Lebendige Aktivitäten unterstützt mit einem Booleschen Wert von YES unter der Hauptanwendungszieldaten der eigenen iOS-Zieldaten anstelle.

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

Ein App-Gruppen-Identifikator ist nur erforderlich, wenn Sie saveImage, removeImage, listImagesoder cleanupImagesbenutzen. Der Plugin extrahiert den App-Gruppen-Identifikator aus dem Hauptanwendungsbundle-Identifikator in genau dieser Formatierung:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Beispielweise muss eine App mit der Bundle-Identifikationsnummer 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 Identifikationsnummer 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 eingebundene Bilder aktivieren Sie auch die Widget-Erweiterung in der Zielmitgliedschaft der Asset.

4. Konfigurieren Sie tiefe Links

Wenn Sie behavior.widgetUrl oder eine Timerfolge tapUrlregistrieren Sie die entsprechende URL-Scheme oder Universal-Link in der Hauptanwendung. Für eine benutzerdefinierte Scheme wie myapp://order/12345Erweitern Sie die App-App-Target unter. Info > URL-Typen Einstellungen.

5. Optional: Aktivieren Sie Servergetriebene Updates

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

• Fügen Sie der Push-Nachrichten Kapazität zur Haupt-App-Target hinzu.
• Erhalten Sie ActivityKit-Push-Token und senden Sie sie an den Server.
• Senden Sie ActivityKit-Nachrichten über APNs mithilfe des liveactivity Push-Typs.
• Hinzufügen NSSupportsLiveActivitiesFrequentUpdates zur Hauptanwendung Info.plist nur dann, wenn der Anwendungsfall 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-Hintergrunddienst.

Native Setup-Checkliste

Bevor Sie startActivity, überprüfen Sie, dass

• NSSupportsLiveActivities aktiviert ist, auf der Zielvorlage der Hauptanwendung.
• Der Widget-Extension ist eingebettet und registriert ein ActivityConfiguration.
• Der native ActivityKit-Implementierung und die Widget-Extension verwenden denselben 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.
• Die entsprechende App-Gruppe ist auf beiden Zielen aktiviert, wenn Shared-Bilder verwendet werden.
• Jeder benutzerdefinierte URL-Schema, das von widgetUrl oder tapUrl Sind Sie auf der Suche nach einer Alternative zu Capgo?

wurde 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-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 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 gemeinsamen Container.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Starten Sie eine Timersequenz für Workouts/Sport. Bei iOS: Sichtbar in Live-Aktivität 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

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

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

Typenverweis

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

Einstellungen 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

Einstellungen 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 Bildspeicherns.

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

RemoveImageOptions

Optionen zum Entfernen einer Abbildung.

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

RemoveImageResult

Ergebnis der Entfernung einer Abbildung.

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

ListImagesResult

Ergebnis der Auflistung von Abbildungen.

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 wird von dem Plugin generiert src/definitions.tsWiederholen Sie die Synchronisierung, wenn die öffentliche API upstream geändert wird.

Weitermachen 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 zur Implementierungsdetail in API Übersicht Einführung zur Implementierungsdetail in Einführung API Schlüssel zur Implementierungsdetail in API Schlüssel und Geräte zur Implementierungsdetail in Geräte.