14 jours d'essai gratuit illimité. Pas de carte de crédit requise

Installez

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite la prompt suivante :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous.

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

Configuration iOS

L'installation et la synchronisation du plugin ne créent pas l'interface utilisateur native de Live Activity. ActivityKit nécessite une extension de Widget qui s'inscrit une configuration de Live Activity avant startActivity peut afficher n'importe quoi.

Exigences

• Utilisez iOS 16.1 ou une version ultérieure pour les deux cibles de l'application et de l'extension Widget.
• Testez sur un appareil iOS ou un simulateur compatible. L'île dynamique ne s'affiche que sur les modèles de dispositifs pris en charge ; les autres appareils utilisent la présentation de la zone de verrouillage.
• Gardez les données combinées d'ActivityKit statiques et dynamiques en dessous de la limite de 4 Ko d'Apple.

1. Créez une extension Widget

Ouvrez le projet iOS natif :

bunx cap open ios

Ensuite :

1. Sélectionner Fichier > Nouveau > Cible.
2. Ajouter un Extension de widget.
3. Activer Inclure l'activité en direct.
4. Désactiver Inclure l'intention de configuration sauf si l'application nécessite également un widget configurable.
5. Vérifiez que l'extension générée est insérée dans la cible de l'application principale.

L'extension de widget doit contenir un ActivityConfiguration et l'enregistrer dans sa WidgetBundle. Il doit fournir toutes les présentations de Live Activity requises :

• Lock Screen
• Dynamic Island étendu
• Dynamic Island compact avec marge avant et arrière
• Île dynamique minimale

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

2. Activer les activités en direct

Ajoutez la clé suivante à la cible de l'application principale : Info.plist:

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

Si le projet génère ses Info.plist, ajoutez Supporte les activités en direct avec une valeur booléenne de YES sous les propriétés de cible iOS personnalisées de la cible principale de l'application.

3. Configurez le groupe d'application pour les images partagées

An App Group is only required when using saveImage, removeImage, listImages, ou cleanupImagesLe plugin déduit l'identifiant de groupe d'application à partir de l'identifiant de bundle principal de l'application sous la forme suivante :

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Par exemple, une application avec l'identifiant de la cible com.example.delivery doit utiliser :

group.com.example.delivery.liveactivities

Dans Xcode, ajoutez la App Groups capacité au cible principal de l'application et à la cible d'extension de Widget, puis activez le même identifiant sur les deux cibles.

Les extensions d'activité en direct ne peuvent pas accéder au réseau. Téléchargez les images distantes dans l'application principale et sauvegardez-les dans le groupe d'application partagé avant de les référencer à partir d'une activité en direct. Pour les images embarquées, activez également l'extension de Widget dans la participation cible de l'actif.

4. Configurer les liens profonds

When using behavior.widgetUrl ou une séquence de temporisateur tapUrlenregistrez le schéma de lien correspondant ou le lien universel dans l'application principale. Pour un schéma personnalisé tel que myapp://order/12345Ajoutez le schéma sous la cible d'application principale. Informations > Types de URL Paramètres.

5. Optionnel : Activer les mises à jour dérivées du serveur

Mises à jour locales ne nécessitent pas de notifications push. Pour démarrer, mettre à jour ou terminer les activités en direct à partir d'un serveur :

• Ajoutez la Notifications Push capacité à la cible principale de l'application.
• Obtenez les jetons de push ActivityKit et envoyez-les au serveur.
• Envoi de notifications ActivityKit via APNs à l'aide de liveactivity type de push.
• Add NSSupportsLiveActivitiesFrequentUpdates Ajoutez à la cible d'application principale Info.plist only when the use case requires frequent push updates.

Les jetons de mise à jour d'ActivityKit sont séparés des jetons de notification utilisateur standard pour appareil. L'activation de la capacité de notifications push seule n'est pas suffisante ; les mises à jour provenant du serveur nécessitent une gestion de jetons natives et un backend APNs.

Checklist de mise en place native

Avant d'appeler startActivityVérifiez que :

• NSSupportsLiveActivities est activé sur la cible d'application principale.
• L'extension Widget est intégrée et enregistre un ActivityConfiguration.
• L'implémentation native d'ActivityKit et l'extension Widget utilisent le même ActivityAttributes type.
• Les cibles de déploiement de l'application et de l'extension Widget sont iOS 16.1 ou ultérieur.
• Les activités Live sont activées pour l'application dans les paramètres iOS.
• Le groupe d'application correspondant est activé sur les deux cibles lors de l'utilisation d'images partagées.
• Tout schéma de URL personnalisé utilisé par widgetUrl ou tapUrl est enregistré.

Importer

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

API Vue d'ensemble

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

Lancer une nouvelle activité Live 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é Live 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

Fermer une activité Live.

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

Obtenir toutes les activités Live actuellement actives.

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

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

saveImage

Enregistrez une image dans le conteneur de groupe d'applications partagé pour l'utiliser dans les activités en direct. Les images doivent être enregistrées dans le conteneur partagé pour être accessibles depuis l'extension de widget.

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

Supprimez une image enregistrée du conteneur partagé.

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

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

listImages

Listez toutes les images sauvegardées dans le conteneur partagé.

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

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

cleanupImages

Supprimez toutes les images enregistrées du conteneur partagé.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Démarrez une séquence de chronométrage pour les entraînements/ sports. Sur iOS : Affiché dans l'activité en direct et dans l'île dynamique Sur Android : Affiché sous forme de notification de fond avec chronomètre

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

Interrompez la séquence de chronométrage.

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

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

resumeTimerSequence

Rétablissez une séquence de chronométrage interrompue.

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

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

stopTimerSequence

Arrêtez et supprimez la séquence de chronométrage.

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

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

skipTimerStep

Passer à l'étape suivante de la séquence.

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

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

previousTimerStep

Retourner à l'étape précédente de la séquence.

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

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

getTimerState

Récupérer l'état actuel d'une séquence de temporisation.

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

Référence de type

AreActivitiesSupportedResult

Résultat de la vérification du support des activités.

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

StartActivityOptions

Options pour démarrer une activité en direct.

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

Résultat de la démarrage d'une activité.

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

UpdateActivityOptions

Options pour mettre à jour une activité en direct.

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

Options pour mettre fin à une activité en direct.

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

Résultat de getAllActivities.

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

SaveImageOptions

Options pour sauvegarder une image.

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

Résultat de la sauvegarde d'une image.

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

RemoveImageOptions

Options pour supprimer une image.

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

RemoveImageResult

Résultat de la suppression d'une image.

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

ListImagesResult

Résultat de la liste des images.

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

TimerSequenceOptions

Options pour démarrer une séquence de temporisation.

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

Source de Vérité

Cette page est générée à partir du plugin’s src/definitions.tsRexécutez la synchronisation lorsque les données publiques API changent en amont.

Continuez de la section "Démarrage rapide"

Si vous utilisez « Getting Started » pour planifier les opérations de tableau de bord et __CAPGO_KEEP_0__ planifier votre tableau de bord et les opérations API, connectez-l’avec Utilisation de @capgo/capacitor-activités en temps réel Pour la capacité native dans l'utilisation de @capgo/capacitor-activités en direct. pour le détail d'implémentation dans « API Overview » Pour les détails d'implémentation dans API Vue d'ensemble. Introduction pour les détails d'implémentation dans l'Introduction. Clés API pour les détails d'implémentation dans les clés API. Appareils pour les détails d'implémentation sur les appareils.