Getting Started

Installer

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 mise en place 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 dans une configuration de Live Activity avant startActivity de pouvoir afficher quoi que ce soit.

Exigences

• Utilisez iOS 16.1 ou une version ultérieure pour les cibles d'application et d'extension de 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 page de verrouillage.
• Gardez les données statiques et dynamiques combinées d'ActivityKit en dessous de la limite de 4 Ko d'Apple.

1. Créez une extension de widget

Ouvrez le projet iOS natif :

bunx cap open ios

Ensuite :

1. Sélectionner Fichier > Nouveau > Cible.
2. Ajouter une Extension de widget.
3. Activer Inclure l'activité en direct.
4. Désactiver Inclure la configuration de l'intention à moins que l'application n'ait également besoin d'un widget configurable.
5. Assurez-vous que l'extension générée soit intégrée dans la cible de l'application principale.

L'extension du Widget 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 élargie
• Île dynamique compacte en tête et en queue
• Île dynamique minimale

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

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

Un groupe d'applications est requis uniquement lors de l'utilisation de saveImage, removeImage, listImages, ou cleanupImages. Le plugin dérive l'identifiant du groupe d'applications à partir de l'identifiant du bundle principal 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é de groupe d'applications à la cible principale de l'application et à la cible d'extension de Widget, puis activez l'identifiant même 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 enregistrez-les dans le groupe d'applications 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 de cible des actifs.

4. Configurez les liens profonds

Lorsque vous utilisez behavior.widgetUrl ou une séquence de temporisation 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 de l'application principale dans Paramètres > Types de URL 5. Optionnel : Activer les mises à jour dérivées du serveur

Section intitulée « 5. Optionnel : Activer les mises à jour dérivées du serveur »

Ajoutez les

• Notifications Push Notifications Push capacité à l'application principale cible.
• Obtenez les jetons de notification ActivityKit et envoyez-les au serveur.
• Envoyer des notifications ActivityKit à l'aide de APNs en utilisant le liveactivity type de notification.
• Ajouter NSSupportsLiveActivitiesFrequentUpdates à l'application principale Info.plist seulement lorsque le cas d'utilisation nécessite des mises à jour de notification push fréquentes.

Les jetons de notification ActivityKit sont séparés des jetons de notification utilisateur standard pour appareil.

L'activation de la capacité aux notifications push seule n'est pas suffisante ; les mises à jour servies 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", vé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 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 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.
• Toute scheme 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

Démarrer une nouvelle activité en direct avec la disposition spécifiée 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

Terminer 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

Obtenir toutes les activités en cours.

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

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

saveImage

Enregistrer une image dans le conteneur partagé App Group 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

Supprimer une image enregistrée du conteneur partagé.

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

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

listImages

Lister 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

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êter et fermer 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

Obtenez 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 lancement 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 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.tsRe-run la synchronisation lorsque le public API change en amont.

Continuez de Getting Started

Si vous utilisez Démarrage pour planifier le tableau de bord et les opérations API, connectez-le à Utilisation de @capgo/capacitor-activités-en-ligne pour la capacité native dans Utilisation de @capgo/capacitor-activités-en-ligne, Vue d'ensemble de API pour le détail d'implémentation dans Vue d'ensemble de API, Introduction pour le détail d'implémentation dans Introduction, Clés de API pour le détail d'implémentation dans Clés de API, et Appareils pour le détail d'implémentation dans Appareils.