Configuración inicial

Instalar

Puedes utilizar nuestra configuración asistida por IA para instalar el plugin. Agrega las Capgo habilidades a tu herramienta de IA utilizando el siguiente comando:

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

Luego utiliza la siguiente solicitud:

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

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas de la plataforma a continuación.

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

iOS Setup

Instalar y sincronizar el complemento no crea la interfaz de usuario nativa de Live Activity. ActivityKit requiere una extensión de Widget que registre una configuración de Live Activity antes de que startActivity pueda mostrar algo.

Requisitos

• Utilice iOS 16.1 o posterior para ambos objetivos de la aplicación y la extensión de Widget.
• Pruebe en un dispositivo iOS o un simulador compatible. La Isla Dinámica solo aparece en modelos de dispositivos compatibles; los demás dispositivos utilizan la presentación de pantalla de bloqueo.
• Mantenga los datos estáticos y dinámicos de ActivityKit combinados por debajo del límite de 4 KB de Apple.

1. Crea una extensión de Widget

Abre el proyecto nativo de iOS:

bunx cap open ios

Luego:

1. Seleccionar Archivo > Nuevo > Destino.
2. Agregar una Extensión de Widget.
3. Habilitar Incluir Actividad en vivo.
4. Deshabilitar Incluir Configuración de Intención a menos que la aplicación también necesite un widget configurable.
5. Asegúrese de que la extensión generada esté integrada en la aplicación principal objetivo.

La Extensión de Widget debe contener un ActivityConfiguration y registrarlo en su WidgetBundle . Debe proporcionar cada presentación de Live Activity requerida:

• Pantalla de bloqueo
• Dynamic Island ampliado
• Dynamic Island compacto en la parte superior e inferior
• Dynamic Island mínimo

Agregar el objetivo solo no es suficiente. La aplicación nativa o el plugin deben llamar a las API de ActivityKit, request, update y end. La extensión debe contener SwiftUI code que pueda descodificar y renderizar lo mismo ActivityAttributes y el estado de contenido utilizado por esas llamadas. Incluya modelos compartidos de ActivityKit en ambos objetivos del app principal y la extensión de Widget. El template de actividad en vivo generado por Xcode no renderiza automáticamente los diseños JSON pasados a este plugin; la extensión también necesita un renderizador de diseños nativos compatible.

2. Habilitar Actividades en Vivo

Add the following key to the main app target’s Info.plist:

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

Si el proyecto genera sus Info.plist, agregue Actividades en Vivo con un valor booleano de YES bajo las propiedades de destino iOS personalizadas del objetivo principal de la aplicación.

3. Configurar el Grupo de Aplicación para Imágenes Compartidas

Un grupo de aplicaciones solo es necesario cuando se utiliza saveImage, removeImage, listImageso cleanupImages. El complemento deriva el identificador del grupo de aplicaciones del identificador del paquete principal de la aplicación utilizando este formato exacto:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Por ejemplo, una aplicación con identificador de paquete com.example.delivery debe utilizar:

group.com.example.delivery.liveactivities

En Xcode, agregue la App Groups a ambos objetivos del paquete principal y la extensión de Widget, y luego habilite el mismo identificador en ambos objetivos.

Las extensiones de actividad en vivo no pueden acceder a la red. Descargue imágenes remotas en la aplicación principal y guárdelas en el grupo de aplicaciones compartido antes de referirse a ellas desde una actividad en vivo. Para imágenes embaladas, también habilite la extensión de Widget en la pertenencia de objetivos del recurso.

4. Configurar enlaces profundos

Cuando se utilice behavior.widgetUrl o una secuencia de temporizador tapUrlregistrar el esquema de URL correspondiente o el enlace universal en la aplicación principal. Para un esquema personalizado como myapp://order/12345, agregar el esquema bajo el objetivo principal de la aplicación Configuración > Tipos de URL settings.

5. Opcional: Habilitar Actualizaciones Servidor-Driven

Las notificaciones push no son necesarias para actualizaciones locales iniciadas por la aplicación. Para empezar, actualizar o finalizar actividades en vivo desde un servidor:

• Agregar el Notificaciones push capacidad al objetivo principal de la aplicación.
• Obtenga tokens de notificación de ActivityKit y envíelos al servidor.
• Enviar notificaciones de ActivityKit a través de APNs utilizando el liveactivity tipo de emisión
• Agregar NSSupportsLiveActivitiesFrequentUpdates al objetivo principal de la aplicación Info.plist solo cuando el caso de uso requiere actualizaciones de empuje frecuentes.

Los tokens de notificación de ActivityKit son separados de los tokens de dispositivo de notificación estándar. Habilitar la capacidad de notificaciones push sola no es suficiente; las actualizaciones impulsadas por el servidor requieren un manejo nativo de tokens y un backend de APNs.

Lista de Verificación de Configuración Nativa

Antes de llamar startActivityverifique que:

• NSSupportsLiveActivities est habilitado en la aplicación principal objetivo.
• La extensión del Widget está integrada y registra un ActivityConfiguration.
• La implementación nativa de ActivityKit y la extensión del Widget utilizan el mismo ActivityAttributes tipo.
• La aplicación y la extensión de Widget se despliegan en iOS 16.1 o posterior.
• Live Activities are enabled for the app in iOS Settings.
• The matching App Group is enabled on both targets when using shared images.
• Cualquier esquema de URL personalizado utilizado por widgetUrl or tapUrl está registrado.

Importar

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

API Introducción

areActivitiesSupported

Verificar si las actividades en vivo están soportadas en este dispositivo. Requiere iOS 16.1+ y soporte de dispositivo.

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

Iniciar una nueva actividad en vivo con el diseño especificado y los datos.

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

Actualizar una actividad en vivo existente con nuevos datos.

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

Finalice una Actividad en vivo.

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

Obtenga todas las Actividades en vivo actualmente activas.

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

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

saveImage

Guarde una imagen en el contenedor de grupo de aplicaciones compartido para su uso en Actividades en vivo. Las imágenes deben guardarse en el contenedor compartido para ser accesibles desde la extensión 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

Elimine una imagen guardada del contenedor compartido.

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

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

listImages

Mostrar todas las imágenes guardadas en el contenedor compartido.

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

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

cleanupImages

Eliminar todas las imágenes guardadas del contenedor compartido.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Iniciar una secuencia de temporizador para ejercicios/deportes. En iOS: Se muestra en la actividad en vivo y en la isla dinámica En Android: Se muestra como una notificación de fondo con temporizador

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

Pausar la secuencia de temporizador.

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

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

resumeTimerSequence

Reanuda una secuencia de temporizador pausada.

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

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

stopTimerSequence

Detener y descartar la secuencia de temporizador.

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

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

skipTimerStep

Saltar al siguiente paso en la secuencia.

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

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

previousTimerStep

Ir al paso anterior en la secuencia.

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

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

getTimerState

Obtenga el estado actual de una secuencia de temporizadores.

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

Referencia de tipo

AreActivitiesSupportedResult

Resultado de verificar si se admiten actividades.

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

StartActivityOptions

Opciones para iniciar una actividad en vivo.

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

Resultado de iniciar una actividad.

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

UpdateActivityOptions

Opciones para actualizar una actividad en vivo.

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

Opciones para finalizar una actividad en vivo.

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

Resultado de obtener todas las actividades.

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

SaveImageOptions

Opciones para guardar una imagen.

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

Resultado de guardar una imagen.

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

RemoveImageOptions

Opciones para eliminar una imagen.

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

RemoveImageResult

Resultado de eliminar una imagen.

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

ListImagesResult

Resultado de la lista de imágenes.

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

TimerSequenceOptions

Opciones para iniciar una secuencia de temporizador.

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

Fuente de Verdad

Esta página se genera a partir del plugin’s src/definitions.tsRe-ruta la sincronización cuando el API público cambie en la fuente.

Sigue adelante desde Inicio

Si estás utilizando Getting Started para planificar la consola y las operaciones API, conectarlo con Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, Resumen de API para el detalle de implementación en Resumen de API, Introducción para el detalle de implementación en Introducción, Claves de API para el detalle de implementación en Claves de API, y Dispositivos Para los detalles de implementación en dispositivos.