Guide
Comment utiliser les Live Activities dans 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 de Live Activity. Avant d’appeler startActivity, configurez ActivityKit dans Xcode :
- Exécutez
bunx cap open ios. - Ajoutez une Cible Widget Extension cible et activer Inclure Live Activity.
- Définissez les cibles de déploiement de l’app et de l’extension Widget sur iOS 16.1 ou version ultérieure.
- Assurez-vous que l’extension est intégrée dans l’app principale.
- Gardez un
ActivityConfigurationenregistré dans le bundle de l’extensionWidgetBundle, avec l’écran verrouillé et toutes les présentations Dynamic Island. - Ajoutez
NSSupportsLiveActivitiesde la cible de l'app principaleInfo.plist.
<key>NSSupportsLiveActivities</key>
<true/>
Ajouter la cible à elle seule ne suffit pas. L'app native ou le plugin doit appeler les API request, update et end d'ActivityKit. La Widget Extension doit contenir du code SwiftUI capable de décoder et d'afficher les mêmes 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
Lorsque vous utilisez les méthodes de gestion d'images, ajoutez la Groupes d’apps capability aux cibles de l'app principale et de la Widget Extension. Activez le même groupe sur les deux cibles avec 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'app principale, enregistrez-les dans l'App Group partagé avec saveImage, puis référencez l'image enregistrée dans le layout. Les assets du bundle doivent aussi appartenir à la cible de la Widget Extension.
Deep links et mises à jour push
- Enregistrez tout schéma d'URL personnalisé utilisé par
behavior.widgetUrloutapUrlsous 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
NSSupportsLiveActivitiesFrequentUpdatesuniquement 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.