Getting Started

Installation

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

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

Ensuite, utilisez 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 Exigences

Section intitulée « Exigences »

• 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 page de verrouillage.
• Assurez-vous de maintenir les données statiques et dynamiques combinées d'ActivityKit en dessous de la limite de 4 Ko imposée par Apple.
• 1. Créez une Extension de Widget

Section intitulée « 1. Créez une Extension de Widget »

Fenêtre de terminal

bunx cap open ios

Ensuite :

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

Le Widget Extension doit contenir un ActivityConfiguration et l'enregistrer dans son WidgetBundle. Il doit fournir chaque présentation de Live Activity requise :

• Écran de verrouillage
• Île dynamique étendue
• Île dynamique compacte avec marge avant et arrière
• Île dynamique minimale

Seule l'ajout de la cible n'est pas suffisant. L'application native ou le plugin doivent appeler les API de demande, de mise à jour et de fin d'ActivityKit. L'extension doit contenir des code SwiftUI qui peuvent décoder et afficher le même ActivityAttributes et état de contenu utilisés par ces appels. Incluez les modèles partagés ActivityKit dans les deux cibles de l'application principale et de l'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 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.plistajoutez 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 au lieu de cela.

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

Un groupe d'application n'est requis que lors de l'utilisation de saveImage, removeImage, listImagesou cleanupImagesLe plugin dérive l'identifiant du groupe d'application à partir de l'identifiant de la cible de l'application principale en utilisant ce format exact :

group.<MAIN_APP_BUNDLE_ID>.liveactivities

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

group.com.example.delivery.liveactivities

Dans Xcode, ajoutez la capacité App Groups à la cible principale de l'application et à la cible d'extension de Widget, puis activez ensuite l'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 App Group 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. Configurez les liens profonds

Lorsque vous utilisez behavior.widgetUrl ou une séquence de temporisateur tapUrl, enregistrez le schéma de URL correspondant ou le lien universel dans l'application principale. Pour un schéma personnalisé tel que myapp://order/12345, ajoutez le schéma sous la cible principale de l'application. Info > Types d'URL Paramètres.

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

Les notifications Push ne sont pas nécessaires pour les mises à jour locales initiées par l'application. Pour commencer, mettre à jour ou terminer les activités en direct à partir d'un serveur :

• Add the Notifications Push context
• Page/zone : Site web de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Clé de message `push_notifications` (Notifications Push).
• ajoutez la capacité à la cible principale de l'application. liveactivity Obtenez les jetons de notification ActivityKit et envoyez-les au serveur.
• Ajouter NSSupportsLiveActivitiesFrequentUpdates au principal application Info.plist seulement lorsque le cas d'utilisation nécessite des mises à jour de poussée fréquentes.

Les jetons de mise à jour de l'ActivityKit sont séparés des jetons de notification standard pour les appareils.

Activer la capacité de notifications Push ne suffit pas ; les mises à jour de serveur nécessitent une gestion native des jetons et un backend APNs.

Section intitulée « Liste de vérification de la mise en place native » startActivityAvant d'appeler

• NSSupportsLiveActivities , vérifiez que
• est activé sur la cible de l'application principale. ActivityConfiguration.
• L'extension Widget est intégrée et enregistre un ActivityAttributes L'implémentation native d'ActivityKit et l'extension Widget utilisent le même
• Les cibles d'application et d'extension Widget sont iOS 16.1 ou ultérieur.
• Les activités en direct 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.
• Quelque schéma d'URL personnalisé utilisé par widgetUrl ou tapUrl Quels sont les avantages de nos solutions alternatives ? Nous vous proposons des solutions alternatives pour vous aider à choisir la meilleure solution pour vos besoins. Nous avons développé des solutions alternatives pour vous aider à migrer vers nos solutions. Nous sommes là pour vous aider à choisir la meilleure solution pour vos besoins.

est enregistré.

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

API Overview

areActivitiesSupported

Vérifiez si les activités en direct sont prises en charge sur cet appareil. Exigez iOS 16.1+ et le support 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

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

getAllActivities

Obtenez 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 Live. Les images doivent être enregistrées dans le conteneur partagé pour être accessibles à partir de 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

Affichez 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

Supprimer toutes les images sauvegardées du conteneur partagé.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Démarrer une séquence de temporisation 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 temporisation

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

Suspendre la séquence de temporisation.

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

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

resumeTimerSequence

Rétablir une séquence de temporisation suspendue.

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

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

stopTimerSequence

Arrêtez et annulez la séquence de temporisation.

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

Obtenir 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 si les activités sont prises en charge.

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 terminer 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 getAllActivités.

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.tsRe-générez la synchronisation lorsque la public API change en amont.

Continuez de la section « Getting Started »

Si vous utilisez Getting Started pour planifier le tableau de bord et les opérations API, connectez-l’avec En utilisant @capgo/capacitor-live-activités pour la capacité native en En utilisant @capgo/capacitor-live-activités, API Présentation pour les détails d'implémentation dans API Présentation, Introduction pour les détails d'implémentation dans Introduction, API Clés pour les détails d'implémentation dans API Clés, et Appareils pour les détails d'implémentation dans Appareils.