Live Activities Capacitor Plugin

@capgo/capacitor-live-activities verwenden

Capacitor Live Activities Plugin zur Verwaltung von iOS Live Activities.

Installieren

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

iOS-Setup

Die Installation und Synchronisierung des Plugins erzeugen nicht die native Live-Activity-UI. Vor dem Aufruf startActivity, konfiguriere ActivityKit in Xcode:

1. Ausführen bunx cap open ios.
2. Füge einen Widget-Extension das Target und aktiviere Live Activity einschließen.
3. Setze die Deployment Targets für die App und die Widget Extension auf iOS 16.1 oder höher.
4. Stelle sicher, dass die Extension in der Haupt-App eingebettet ist.
5. Behalte eine ActivityConfiguration in der Extension registriert WidgetBundle, mit Lock Screen und allen Dynamic-Island-Darstellungen.
6. Füge NSSupportsLiveActivities der Haupt-App-Target Info.plist.

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

Das Hinzufügen des Targets allein reicht nicht aus. Die native App oder das Plugin muss die APIs von ActivityKit für request, update und end aufrufen. Die Widget Extension muss SwiftUI code enthalten, die denselben ActivityAttributes und Content-State dekodieren und rendern können, der von diesen Aufrufen verwendet wird. Integriere gemeinsame ActivityKit-Modelle sowohl im Haupt-App- als auch im Widget Extension Target. Das von Xcode generierte Live Activity Template rendert die an dieses Plugin übergebenen JSON-Layouts nicht automatisch; die Extension benötigt ebenfalls einen kompatiblen nativen Layout-Renderer.

Gemeinsame Bilder

Wenn du die Image-Management-Methoden nutzt, füge die App-Gruppen Capability zum Haupt-App- und Widget Extension Target hinzu. Aktiviere dieselbe Gruppe auf beiden Targets mit der exakten Identifier, die das Plugin erwartet:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Live Activity Extensions haben keinen Netzwerkzugriff. Lade Remote-Bilder in der Haupt-App herunter, speichere sie in der gemeinsamen App Group mit saveImage, und referenziere das gespeicherte Bild dann im Layout. Bundled Assets müssen ebenfalls zum Widget Extension Target gehören.

Deep Links und Push Updates

• Registriere alle Custom URL Schemes, die von behavior.widgetUrl oder tapUrl unter den Einstellungen des Haupt-App-Targets Info > URL Types unter
• Für servergesteuerte Updates füge die Push-Benachrichtigungen Capability hinzu und implementiere das ActivityKit Push-Token-Handling via APNs.
• Füge NSSupportsLiveActivitiesFrequentUpdates nur wenn die App häufige ActivityKit Push-Updates benötigt.

Das Aktivieren der Push Notifications Capability allein reicht nicht aus; servergesteuerte Updates erfordern natives Token-Handling und ein APNs-Backend.

ActivityKit begrenzt die kombinierten statischen und dynamischen Live Activity Daten auf 4 KB. Die Dynamic Island ist nur auf unterstützten Modellen sichtbar; andere Geräte nutzen die Lock Screen Darstellung.

Was dieses Plugin bereitstellt

• areActivitiesSupported - Prüfen, ob Live Activities auf diesem Gerät unterstützt werden. Erfordert iOS 16.1+ und Geräteunterstützung.
• startActivity - Eine neue Live Activity mit dem angegebenen Layout und den angegebenen Daten starten.
• updateActivity - Eine bestehende Live Activity mit neuen Daten aktualisieren.
• endActivity - Eine Live Activity beenden.

Anwendungsbeispiel

areActivitiesSupported

Prüfen, ob Live Activities auf diesem Gerät unterstützt werden. Erfordert 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

Eine neue Live Activity mit dem angegebenen Layout und den angegebenen Daten starten.

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

Eine bestehende Live Activity 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

Eine 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
});

Vollständige Referenz

• GitHub: https://github.com/Cap-go/capacitor-live-activities/
• Docs: /docs/plugins/live-activities/

Weiter mit der Nutzung von @capgo/capacitor-live-activities

Wenn du es nutzt @capgo/capacitor-live-activities verwenden , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Erste Schritte für die Implementierungsdetails in Erste Schritte, Verwendung von @capgo/capacitor-video-player für die native Funktion bei Verwendung von @capgo/capacitor-video-player, @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player und Verwendung von @capgo/capacitor-native-navigation für die native Funktion bei Verwendung von @capgo/capacitor-native-navigation.