Widget Kit plugin Capacitor

Uso de @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit permite que una app Capacitor gestione WidgetKit y Live Activity de dos formas:

• Renderiza superficies de plantillas SVG con cambio de frames, hotspots táctiles y temporizadores de pausa/reproducción.
• Mantén el widget totalmente nativo mientras la app y el widget comparten el estado de sesión JSON y mensajes asíncronos.

Instalar

bun add @capgo/capacitor-widget-kit
bunx cap sync

Cuándo usar plantillas SVG

Usa plantillas SVG cuando la superficie del widget se pueda describir como un SVG. La app guarda la definición de la plantilla, el bridge nativo resuelve los placeholders y los taps en el widget pueden mutar el estado después.

Casos ideales: timers de entrenamiento, tarjetas de estado de entrega, resultados deportivos o cualquier UI compacta donde cambiar entre frames sea suficiente.

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
      },
      {
        id: 'toggle-rest',
        timerMutations: [{ op: 'toggle', timerId: 'rest' }],
      },
    ],
    layouts: {
      lockScreen: {
        width: 100,
        height: 40,
        frameIdPath: 'state.frame',
        frames: [
          {
            id: 'summary',
            hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{state.title}}</text></svg>`,
          },
          {
            id: 'timer',
            hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{timers.rest.remainingText}}</text></svg>`,
          },
        ],
      },
    },
  },
});

Gestionar acciones del widget en la app

Las acciones del widget se guardan como eventos. Léelos y confírmalos al reanudar la app o tras una sincronización en segundo plano.

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log(event.actionId, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({ activityId: activity.activityId });

Cuándo usar sesiones Full-Native

Usa sesiones full-native cuando la UI del widget se construya mejor directamente en Swift, Kotlin o Java. Capacitor sigue gestionando el inicio y fin de la sesión, mantiene el estado compartido y encola el trabajo entre la app y el widget code.

const { session } = await CapgoWidgetKit.startWidgetSession({
  widgetId: 'native-session-1',
  kind: 'workout-controls',
  state: { isRunning: true, selectedSetId: 'set-1' },
  metadata: { accent: '#00d69c' },
});

await CapgoWidgetKit.updateWidgetSession({
  widgetId: session.widgetId,
  merge: true,
  state: { isRunning: false },
});

Encola trabajo asíncrono entre el widget y la app

Los mensajes pueden fluir de la app al widget o viceversa. Permanecen pendientes hasta que se confirman y completan.

const { message } = await CapgoWidgetKit.sendWidgetMessage({
  widgetId: session.widgetId,
  direction: 'widgetToApp',
  name: 'syncWorkoutSet',
  payload: { setId: 'set-1' },
  expectsResponse: true,
});

await CapgoWidgetKit.acknowledgeWidgetMessages({ messageIds: [message.messageId] });

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  response: { synced: true },
});

Si la tarea falla, completa el mensaje con un error:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

Detén las sesiones correctamente

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

Notas de configuración nativa

Para iOS WidgetKit y Live Activities, configura un App Group en los targets de la app y de la extensión del widget y establece CapgoWidgetKitAppGroup en ambos Info.plist files. Los botones interactivos requieren una extensión de widget que conecte el bridge nativo del plugin con el action intent.

Referencia completa

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• Docs: /docs/plugins/widget-kit/

Continuar desde Uso de @capgo/capacitor-widget-kit

Si estás usando Uso de @capgo/capacitor-widget-kit para planificar el trabajo con plugins nativos, conéctalo con @capgo/capacitor-widget-kit para los detalles de implementación en @capgo/capacitor-widget-kit, Primeros pasos para los detalles de implementación en Primeros pasos, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para los detalles de implementación en Capacitor Plugins de Capgo, y Añadir o actualizar plugins para los detalles de implementación al añadir o actualizar plugins.