Activités en direct Plugin Capacitor

Utiliser @capgo/capacitor-live-activities

Interface du plugin Capacitor Live Activities pour gérer les Live Activities sur iOS.

Installer

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

Configuration iOS

L'installation et la synchronisation du plugin ne créent pas l'interface native Live Activity. Avant d'appeler startActivity, configurez ActivityKit dans Xcode :

1. Exécutez bunx cap open ios.
2. Ajoutez une la cible Widget Extension cibler et activer Inclure les Live Activities.
3. Définissez les cibles de déploiement de l'app et de la Widget Extension sur iOS 16.1 ou version ultérieure.
4. Assurez-vous que l'extension est intégrée à l'application principale.
5. Conservez un ActivityConfiguration enregistré dans l'extension WidgetBundle, avec l'écran de verrouillage et toutes les présentations Dynamic Island.
6. Ajoutez NSSupportsLiveActivities de la cible de l'application principale Info.plist.

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

Ajouter la cible seule ne suffit pas. L'application native ou le plugin doit appeler les API request, update et end d'ActivityKit. La Widget Extension doit contenir du SwiftUI code capable de décoder et de rendre le même ActivityAttributes et l'état de contenu utilisés par ces appels. Incluez les modèles ActivityKit partagés dans les cibles de l'application principale et de l'extension Widget. Le template Live Activity généré par Xcode n'affiche pas automatiquement les layouts JSON passés à ce plugin ; l'extension a aussi besoin d'un moteur de rendu de layout natif compatible.

Images partagées

Lors de l'utilisation des méthodes de gestion d'images, ajoutez la App Groups capability aux cibles de l'application principale et de la Widget Extension. Activez le même groupe sur les deux cibles en utilisant l'identifiant exact attendu par le plugin :

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Les extensions Live Activity ne peuvent pas accéder au réseau. Téléchargez les images distantes dans l'application principale, enregistrez-les dans l'App Group partagé avec saveImage, puis référez-vous à l'image enregistrée depuis le layout. Les assets du bundle doivent également appartenir à la cible de la Widget Extension.

Deep Links et Push Updates

• Enregistrez tout schéma d'URL personnalisé utilisé par behavior.widgetUrl ou tapUrl sous le target principal de l'app Info > URL Types réglages.
• For server-driven updates, add the Notifications push capacité et implémentez la gestion des tokens push ActivityKit avec APNs.
• Ajoutez NSSupportsLiveActivitiesFrequentUpdates uniquement lorsque l'app nécessite des mises à jour push ActivityKit fréquentes.

L'activation seule de la capacité Push Notifications ne suffit pas ; les mises à jour pilotées par le serveur nécessitent la gestion des tokens natifs et un backend APNs.

ActivityKit limite à 4 Ko les données statiques et dynamiques combinées des Live Activities. La Dynamic Island n'est visible que sur les modèles d'appareils compatibles ; les autres appareils utilisent l'affichage sur l'écran de verrouillage.

Ce que ce plugin expose

• areActivitiesSupported - Vérifier si les Live Activities sont prises en charge sur cet appareil. Nécessite iOS 16.1+ et un appareil compatible.
• startActivity - Démarrer une nouvelle Live Activity avec le layout et les données spécifiés.
• updateActivity - Mettre à jour une Live Activity existante avec de nouvelles données.
• endActivity - Terminer une Live Activity.

Exemple d'utilisation

areActivitiesSupported

Vérifier si les Live Activities sont prises en charge sur cet appareil. Nécessite iOS 16.1+ et un appareil compatible.

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

Démarrer une nouvelle Live Activity avec le layout et les données spécifiés.

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

Mettre à jour une Live Activity existante avec de nouvelles données.

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

Terminer une Live Activity.

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

Référence complète

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

Continuer depuis la section Utiliser @capgo/capacitor-live-activities

Si vous utilisez Utiliser @capgo/capacitor-live-activities pour planifier le comportement des médias et de l'interface natifs, connectez-l’à @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Prise en main pour les détails d'implémentation dans Getting Started Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans la section Utiliser @capgo/capacitor-video-player, @capgo/capacitor-video-player pour les détails d'implémentation dans @capgo/capacitor-video-player, et Utilisation de @capgo/capacitor-native-navigation pour la fonctionnalité native dans Using @capgo/capacitor-native-navigation.