Allez directement au contenu principal
Retour aux plugins
@capgo/capacitor-activités-en-vivre
Tutoriel
@capgo/capacitor-activités-en-vivre

Activités en direct

Gérez les activités en direct iOS et les dispositions de l'île dynamique à partir de Capacitor avec des modèles JSON

Guide

Tutoriel sur les activités en direct

Utilisation de @capgo/capacitor-live-activities

Capacitor : interface de plugin d'activités en direct pour 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 de l'activité native. Avant d'appeler startActivityconfigurez ActivityKit dans Xcode :

  1. Exécuter bunx cap open ios.
  2. Ajoutez un Extension de widget cible et activez Incluez une activité en direct.
  3. Définissez les cibles de déploiement de l'application et de l'extension de widget sur iOS 16.1 ou ultérieur.
  4. Assurez-vous que l'extension est intégrée à l'application principale.
  5. gardez un ActivityConfiguration enregistré dans l'extension's WidgetBundle, avec la zone de verrouillage et toutes les présentations de Dynamic Island.
  6. Ajoutez NSSupportsLiveActivities à la cible de l'application principale's Info.plist.
<key>NSSupportsLiveActivities</key>
<true/>

L'ajout de la cible seule n'est pas suffisant. L'application native ou le plugin doivent appeler les API request, update et end d'ActivityKit. L'extension de widget doit contenir des code SwiftUI qui peuvent décoder et afficher les mêmes ActivityAttributes et l'état de contenu utilisé par ces appels. Incluez les modèles d'ActivityKit partagés dans les deux cibles principales et d'extension de Widget. Le modèle de Live Activity généré par Xcode ne rend pas automatiquement les layouts JSON transmis à ce plugin ; l'extension nécessite également un rendu de layout natif compatible.

Images partagées

Lors de l'utilisation des méthodes de gestion d'images, ajoutez le Groupes d'applications capacité à la cible principale et à l'extension de Widget. 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 de Live Activity ne peuvent pas accéder au réseau. Téléchargez les images distantes dans l'app principale, enregistrez-les dans le groupe d'applications partagé avec saveImage, et référez ensuite à l'image enregistrée à partir de la mise en page. Les ressources embarquées doivent également appartenir à la cible de l'extension de Widget.

Liens profonds et mises à jour Push

  • Inscrivez tout schéma de lien personnalisé utilisé par behavior.widgetUrl ou tapUrl enregistrer les liens profonds et les mises à jour Push dans l'app principale et l'extension de Widget. Les extensions de Live Activity ne peuvent pas accéder au réseau. enregistrer les liens profonds et les mises à jour Push dans l'app principale et l'extension de Widget. Les extensions de Live Activity ne peuvent pas accéder au réseau. Paramètres.
  • Pour les mises à jour dérivées du serveur, ajoutez la Notifications Push context
  • Page/area: Site de marketing Capgo. Role: Étiquette de navigation ou élément UI court. Clé de message `push_notifications` (Notifications Push). NSSupportsLiveActivitiesFrequentUpdates capacité et implémentez le traitement de jetons d'activité avec APNs.

Ajoutez

seulement lorsque l'application nécessite des mises à jour fréquentes d'activité avec APNs.

Activer la capacité de Notifications Push seule n'est pas suffisant ; les mises à jour dérivées du serveur nécessitent un traitement de jetons natifs et un backend APNs.

  • areActivitiesSupported ActivityKit limite les données de Live Activity statiques et dynamiques combinées à 4 Ko. L'île dynamique n'est visible que sur les modèles de dispositifs pris en charge ; les autres appareils utilisent la présentation de la zone de verrouillage.
  • startActivity Ce que ce plugin expose
  • updateActivity - Vérifiez si les activités en direct sont prises en charge sur cet appareil. Exige iOS 16.1+ et support du dispositif.
  • endActivity - Mettre fin à une activité en direct.

Exemple d'utilisation

areActivitiesSupported

Vérifiez si les activités en direct sont prises en charge sur cet appareil. Exige iOS 16.1+ et prise en charge de l'appareil.

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 activité en direct avec le layout spécifié et les données.

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 activité en direct 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

Mettre fin à une activité en direct.

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

Continuez à partir de l'utilisation de @capgo/capacitor-activités-en-direct

Si vous utilisez En utilisant @capgo/capacitor-live-activités pour planifier le comportement de médias et d'interface natifs, la connecter avec @capgo/capacitor-live-activités pour les détails d'implémentation dans @capgo/capacitor-live-activités, Pour commencer pour les détails d'implémentation dans Pour commencer, En utilisant @capgo/capacitor-player vidéo pour la capacité native dans En utilisant @capgo/capacitor-player vidéo, @capgo/capacitor-player vidéo pour les détails d'implémentation dans @capgo/capacitor-player vidéo, et En utilisant @capgo/capacitor-navigation native pour la capacité native dans En utilisant @capgo/capacitor-navigation native.