Actividades en vivo plugin Capacitor

Uso de @capgo/capacitor-live-activities

Interfaz del plugin Capacitor Live Activities para gestionar Live Activities en iOS.

Instalar

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

iOS Setup

Instalar y sincronizar el plugin no crea la interfaz nativa de Live Activity. Antes de llamar a startActivity, configura ActivityKit en Xcode:

1. Ejecuta bunx cap open ios.
2. Añade una extensión de widget el target y habilita Incluir Live Activity.
3. Establece los deployment targets de la app y la Widget Extension a iOS 16.1 o superior.
4. Asegúrate de que la extensión esté embebida en la app principal.
5. Mantén un ActivityConfiguration registrado en la extensión de WidgetBundle, con la Lock Screen y todas las presentaciones de Dynamic Island.
6. Añadir NSSupportsLiveActivities del target principal de la app Info.plist.

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

Solo añadir el target no es suficiente. La app nativa o el plugin deben llamar a las APIs de request, update y end de ActivityKit. El Widget Extension debe contener code de SwiftUI que puedan decodificar y renderizar lo mismo ActivityAttributes y el estado de contenido usados en esas llamadas. Incluye modelos de ActivityKit compartidos tanto en el target de la app principal como en el de la Widget Extension. La plantilla de Live Activity generada por Xcode no renderiza automáticamente los layouts JSON pasados a este plugin; la extensión también necesita un renderer de layout nativo compatible.

Imágenes compartidas

Al usar los métodos de gestión de imágenes, añade la App Groups capability a los targets de la app principal y del Widget Extension. Habilita el mismo grupo en ambos targets usando el identificador exacto que espera el plugin:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Las extensiones de Live Activity no tienen acceso a la red. Descarga las imágenes remotas en la app principal, guárdalas en el App Group compartido con saveImage, y luego referencia la imagen guardada desde el layout. Los assets del bundle también deben pertenecer al target del Widget Extension.

Deep Links y Push Updates

• Registra cualquier esquema de URL personalizado usado por behavior.widgetUrl o tapUrl dentro del target principal de la app Info > URL Types de configuración.
• Para actualizaciones desde el servidor, añade la Notificaciones push capability e implementa el manejo de push-tokens de ActivityKit con APNs.
• Añadir NSSupportsLiveActivitiesFrequentUpdates solo si la app requiere actualizaciones frecuentes de ActivityKit vía push.

Activar solo la capability de Push Notifications no es suficiente; las actualizaciones desde el servidor requieren el manejo de tokens nativos y un backend de APNs.

ActivityKit limita los datos combinados (estáticos y dinámicos) de Live Activity a 4 KB. La Dynamic Island solo es visible en modelos compatibles; otros dispositivos usan la Lock Screen.

Lo que expone este plugin

• areActivitiesSupported - Comprueba si el dispositivo es compatible con Live Activities. Requiere iOS 16.1+.
• startActivity - Inicia una nueva Live Activity con el layout y los datos especificados.
• updateActivity - Actualiza una Live Activity existente con nuevos datos.
• endActivity - Finaliza una Live Activity.

Ejemplo de uso

areActivitiesSupported

Comprueba si el dispositivo es compatible con Live Activities. Requiere iOS 16.1+.

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 Live Activity con el layout y los datos especificados.

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 Live Activity 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 Live Activity.

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

Referencia completa

• GitHub: https://github.com/Cap-go/capacitor-live-activities/
• Docs: /docs/plugins/live-activities/

Continúa desde Uso de @capgo/capacitor-live-activities

Si estás usando Uso de @capgo/capacitor-live-activities para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Primeros pasos para los detalles de implementación en Primeros pasos, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, @capgo/capacitor-video-player por los detalles de implementación en @capgo/capacitor-video-player, y Uso de @capgo/capacitor-native-navigation para la capacidad nativa al usar @capgo/capacitor-native-navigation.