Inicio

Instalar

Puede utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. Agregue las Capgo habilidades a su herramienta de inteligencia artificial utilizando el siguiente comando:

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

Luego utilice el siguiente prompt:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas del plataforma a continuación:

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

Configuración para iOS

La instalación y sincronización del complemento no crean 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 startActivity pueder mostrar algo.

Requisitos

• Utilice iOS 16.1 o posterior para ambas metas 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 combinados de ActivityKit por debajo del límite de 4 KB de Apple.

1. Crea una extensión de Widget

Abra el proyecto de iOS nativo:

bunx cap open ios

Luego:

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

El Widget Extension debe contener un ActivityConfiguration y registrarlo en su WidgetBundle. Debe proporcionar cada presentación de actividad en vivo requerida:

• Escritorio de pantalla bloqueada
• Island Dinámico ampliado
• Island Dinámico compacto con texto de encabezado y pie de página
• Island Dinámico mínimo

Agregar el objetivo solo no es suficiente. La aplicación nativa o el complemento deben llamar a las API de solicitud, actualización y finalización de ActivityKit. El complemento debe contener SwiftUI code que pueda descodificar y renderizar el mismo ActivityAttributes y estado de contenido utilizado por esas llamadas. Incluya modelos compartidos de ActivityKit en ambos objetivos de aplicación principal y Widget Extension. El plantilla de actividad en vivo generada por Xcode no renderiza automáticamente las disposiciones de JSON pasadas a este complemento; el complemento también necesita un renderizador de disposiciones nativas compatibles.

2. Habilitar Actividades en vivo

Agregue la siguiente clave al objetivo de aplicación principal’s Info.plist:

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

Si el proyecto genera sus Info.plistagrega Funciona con Actividades en vivo con un valor booleano de YES bajo las propiedades de objetivo iOS personalizado del objetivo principal en lugar de eso.

3. Configura el grupo de la aplicación para imágenes compartidas

Un grupo de la aplicación solo se requiere cuando se utiliza saveImage, removeImage, listImages, o cleanupImages. El plugin deriva el identificador del grupo de la aplicación del identificador del paquete de la aplicación principal 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 Capacidad de grupos de aplicación a ambos objetivos del target principal y del target de la extensión de Widget, 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 aplicación compartido antes de referenciarlas desde una actividad en vivo. Para imágenes empaquetadas, también habilite la extensión de Widget en la pertenencia de objetivo de activos.

4. Configurar enlaces profundos

Cuando se utiliza behavior.widgetUrl o una secuencia de temporizador tapUrl, registre el esquema de URL correspondiente o el enlace universal en la aplicación principal. Para un esquema personalizado como myapp://order/12345agregue el esquema bajo el objetivo principal de la aplicación Info > Tipos de URL configuraciones.

5. Opcional: Habilitar Actualizaciones Servidor-Driven

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

• Agregar el capacidad de notificaciones de Push a la objetivo principal de la aplicación. Obtener tokens de notificación de ActivityKit y enviarlos al servidor.
• Enviar notificaciones de ActivityKit a través de APNs utilizando el
• tipo de notificación. liveactivity Configuración > Tipos de URL
• Agregar NSSupportsLiveActivitiesFrequentUpdates a la aplicación principal Info.plist solamente cuando el caso de uso requiere actualizaciones de empuje frecuentes.

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

Lista de Verificación de Configuración Nativa

Antes de llamar startActivity, verifica que:

• NSSupportsLiveActivities esté habilitado en la aplicación principal objetivo.
• La extensión de Widget se integra y registra un ActivityConfiguration.
• La implementación nativa de ActivityKit y la extensión de Widget utilizan el mismo ActivityAttributes tipo.
• The app and Widget Extension deployment targets are iOS 16.1 or later.
• Las actividades en vivo están habilitadas para la aplicación en iOS Settings.
• El grupo de aplicación correspondiente está habilitado en ambos objetivos cuando se utilizan imágenes compartidas.
• Cualquier esquema de URL personalizado utilizado por widgetUrl o tapUrl ¿Qué alternativas tenemos?

¿Qué alternativas tenemos?

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

API Overview

areActivitiesSupported

Verifique 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

Inicia 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

Actualiza 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

Finaliza 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 activas actualmente.

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

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

saveImage

Guardar una imagen en el contenedor compartido de App Group 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

Eliminar una imagen guardada del contenedor compartido.

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

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

listImages

Listar 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

Elimine todas las imágenes guardadas del contenedor compartido.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Inicie 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 primer plano 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

Reanude una secuencia de temporizador pausada.

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

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

stopTimerSequence

Detener y deshacer la secuencia del 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

Volver al paso anterior en la secuencia.

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

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

getTimerState

Obtener 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 tipos

AreActivitiesSupportedResult

Resultado de verificar si las actividades están admitidas.

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 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 listar 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.ts. Vuelva a sincronizar cuando los cambios públicos API cambien en la fuente

Siga adelante desde Getting Started

Si está utilizando Getting Started para planificar la consola y API operaciones, conecte con Usando @capgo/capacitor-live-actividades para la capacidad nativa en Usando @capgo/capacitor-live-actividades, API Resumen para el detalle de implementación en API Resumen, Introducción para el detalle de implementación en Introducción, API Claves para el detalle de implementación en API Claves, y Dispositivos para el detalle de implementación en Dispositivos.