Démarrage

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 l'activité en direct. ActivityKit nécessite une extension de widget qui s'inscrit dans une configuration d'activité en direct avant startActivity de pouvoir afficher quoi que ce soit.

Exigences

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

1. Créez une extension de Widget

Ouvrez le projet iOS natif :

bunx cap open ios

Ensuite :

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

L'Extension de Widget doit contenir un ActivityConfiguration et l'enregistrer dans son WidgetBundle. Il doit fournir chaque présentation d'activité en direct requise :

• Ecran de verrouillage
• Dynamic Island étendu
• Dynamic Island compacté en tête et en queue
• Dynamic Island minimal

La simple ajout du cible n'est pas suffisant. L'application native ou le plugin doit appeler les API de demande, de mise à jour et de fin de ActivityKit. L'extension doit contenir du SwiftUI code qui peut décoder et afficher le même ActivityAttributes et l'état de contenu utilisé 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/>

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

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, listImages, ou cleanupImages. Le plugin dérive l'identifiant du groupe d'application à partir de l'identifiant de la cible principale à l'aide de ce format exact :

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

In Xcode, ajoutez la Groupes d'application capacité à la cible principale 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 à distance 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'asset.

4. Configurez les liens profonds

Lorsque vous utilisez behavior.widgetUrl ou une séquence de temporisateur tapUrl, enregistrez le schéma d'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 les paramètres Info > Types d'URL de la cible principale de l'application.

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 démarrer, mettre à jour ou terminer les activités en direct à partir d'un serveur :

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

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

Liste de vérification de mise en place native

Vérifiez que : startActivityest activé sur la cible d'application principale.

• NSSupportsLiveActivities L'extension Widget est intégrée et s'enregistre un
• L'implémentation native d'ActivityKit et l'extension Widget utilisent le même ActivityConfiguration.
• type. ActivityAttributes L'application et les cibles de déploiement 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.
• Section titled “Native Setup Checklist”
• Toute URL de schéma personnalisée utilisée par widgetUrl ou tapUrl est enregistrée.

Importer

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

API Aperçu

areActivitiesSupported

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

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

Obtenir toutes les activités en direct 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 à 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

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 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 enregistré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 premier plan 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

Mettre en pause 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 mise en pause.

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

Sauter à 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

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 supportées.

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 de l'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;
}

Vérité première

Cette page est générée à partir du plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le tableau de bord et les opérations API, connectez-le avec 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 les détails d’implémentation dans Vue d’ensemble de API, 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.