Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque 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 native de la Live Activity. ActivityKit nécessite une Widget Extension qui enregistre une configuration de Live Activity avant de startActivity pouvoir afficher quoi que ce soit.

Prérequis

• Utilisez iOS 16.1 ou une version ultérieure pour la cible de l'app et la cible de l'extension Widget.
• Testez sur un appareil iOS ou un simulateur compatible. La Dynamic Island n'apparaît que sur les modèles d'appareils compatibles ; les autres utilisent l'affichage sur l'écran de verrouillage.
• Maintenez les données combinées (statiques et dynamiques) d'ActivityKit sous la limite de 4 Ko d'Apple.

1. Créer une extension de widget

Ouvrez le projet iOS natif :

bunx cap open ios

Ensuite :

1. Sélectionnez Fichier > Nouveau > Cible.
2. Ajoutez une Extension de widget.
3. Activer Inclure les Live Activities.
4. Disable Inclure l'intention de configuration à moins que l'application n'ait aussi besoin d'un widget configurable.
5. Assurez-vous que l'extension générée est intégrée à la cible de l'application principale.

L'extension Widget doit contenir un ActivityConfiguration et l'enregistrer dans son WidgetBundle. Elle doit fournir toutes les présentations Live Activity requises :

• Écran verrouillé
• Dynamic Island étendue
• Dynamic Island compacte (leading et trailing)
• Dynamic Island minimale

Le simple ajout de la cible ne suffit pas. L'application native ou le plugin doit appeler les API request, update et end d'ActivityKit. L'extension doit contenir du code SwiftUI capable de décoder et d'afficher 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.

2. Activer les Live Activities

Ajoutez la clé suivante à la cible de l’app principale Info.plist:

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

Si le projet génère son Info.plist, ajoutez Prend en charge les Live Activities avec une valeur booléenne de YES sous les propriétés du target iOS personnalisé de l'application principale à la place.

3. Configurer l'App Group pour les images partagées

Un App Group n’est requis que lorsque vous utilisez saveImage, removeImage, listImages, ou cleanupImages. Le plugin déduit l'identifiant de l'App Group à partir de l'identifiant de bundle de l'application principale, selon ce format exact :

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Par exemple, une application dont l'identifiant de bundle est com.example.delivery doit utiliser :

group.com.example.delivery.liveactivities

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

Les extensions Live Activity n'ont pas accès au réseau. Téléchargez les images distantes dans l'application principale et enregistrez-les dans l'App Group partagé avant de les référencer depuis une Live Activity. Pour les images intégrées au bundle, activez également l'extension Widget dans l'appartenance à la cible de l'asset.

4. Configurer les deep links

When using behavior.widgetUrl ou d'une séquence de minuteur tapUrl, enregistrez le schéma d'URL ou le lien universel correspondant dans l'application principale. Pour un schéma personnalisé tel que myapp://order/12345, ajoutez le schéma sous la cible de l'application principale dans Info > Types d'URL réglages.

5. Facultatif : activer les mises à jour serveur

Les notifications push ne sont pas requises pour les mises à jour locales initiées par l'application. Pour démarrer, mettre à jour ou terminer des Live Activities depuis un serveur :

• Ajoutez la Notifications push capability à la cible de l'application principale.
• Récupérez les tokens push ActivityKit et envoyez-les au serveur.
• Envoyez des notifications ActivityKit via APNs en utilisant le liveactivity type de push.
• Ajoutez NSSupportsLiveActivitiesFrequentUpdates à l'application principale Info.plist uniquement si le cas d'usage nécessite des mises à jour push fréquentes.

Les tokens push ActivityKit sont distincts des tokens d'appareil standard pour les notifications utilisateur. L'activation seule de la capacité Push Notifications ne suffit pas ; les mises à jour pilotées par le serveur nécessitent une gestion native des tokens et un backend APNs.

Checklist de configuration native

Avant d'appeler startActivity, vérifiez que :

• NSSupportsLiveActivities is enabled on the main app target.
• L'extension de widget est intégrée et enregistre un ActivityConfiguration.
• L'implémentation native d'ActivityKit et l'extension de widget utilisent le même ActivityAttributes type.
• Les cibles de déploiement de l'app et de l'extension Widget sont iOS 16.1 ou ultérieur.
• Les Live Activities sont activées pour l'app dans les Réglages iOS.
• L'App Group correspondant est activé sur les deux cibles si vous utilisez des images partagées.
• Tout schéma d'URL personnalisé utilisé par widgetUrl ou tapUrl est enregistré.

Importer

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

Démarrage rapide

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

Exemple : startActivity

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

Exemple : updateActivity

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

Erreurs courantes

• Écouteurs: supprimez les handles lors du démontage des écrans.
• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Aperçu de API

areActivitiesSupported

Vérifie si les Live Activities sont prises en charge sur cet appareil. Nécessite iOS 16.1+ et la compatibilité 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 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
});

getAllActivities

Récupérer toutes les Live Activities 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 partagé de l'App Group pour l'utiliser dans les Live Activities. Les images doivent être enregistrées dans le conteneur partagé pour être accessibles depuis l'extension du 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 enregistré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

Lancez une séquence de timer pour les entraînements et le sport. Sur iOS : s'affiche dans la Live Activity et la Dynamic Island Sur Android : s'affiche comme notification de premier plan avec le timer

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

Mettez la séquence de timer en pause.

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

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

resumeTimerSequence

Reprenez une séquence de timer en pause.

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

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

stopTimerSequence

Arrêtez et fermez la séquence de timer.

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

Revenir à 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 timer.

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 de la compatibilité 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 Live Activity.

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 du démarrage d'une activité.

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

UpdateActivityOptions

Options pour mettre à jour une Live Activity.

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 terminer une Live Activity.

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 enregistrer 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 l'enregistrement 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 l'énumération des images.

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

TimerSequenceOptions

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

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 de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.