Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

Importar

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

Inicio rápido

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

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

Ejemplo: startTemplateActivity

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

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Ejemplo: startTemplateWidget

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

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Errores comunes

• Sync nativo: ejecuta bunx cap sync tras actualizar los plugins.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

iOS Setup

Para Live Activities y extensiones de WidgetKit, configura primero la app nativa:

• Usa iOS 17+ para los botones interactivos de Live Activity cuando sea posible.
• Añadir NSSupportsLiveActivities a la app Info.plist al usar ActivityKit.
• Agrega el mismo App Group tanto al target de la app como al del widget extension.
• Configurar CapgoWidgetKitAppGroup en ambos Info.plist archivos al identificador del App Group compartido.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Comprobar soporte

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

Opción 1: Actividad con plantilla SVG

Usa este modo cuando el widget pueda renderizar el SVG resuelto. El plugin gestiona el estado, resuelve placeholders, aplica tap actions, cambia los frames del SVG y mantiene la consistencia del timer.

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

Ejecutar acciones desde la app

Los widgets nativos pueden activar las mismas acciones mediante su configuración de hotspots/actions. La app también puede ejecutarlas directamente:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Procesar eventos del widget

Las acciones emiten eventos para que la app pueda procesar las interacciones del widget tras su lanzamiento o reanudación:

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

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

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

En iOS, los botones de la extensión del widget pueden invocar helpers LiveActivityIntent empaquetados (CapgoTemplateActionIntent) que escriben en el mismo log de eventos. Esto es independiente de las frases de Siri o la app Shortcuts. Ver Siri, Shortcuts y widgets.

Actualizar o finalizar la actividad

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

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

Mutaciones de frame

Las frame mutations escriben el id del frame activo en el estado. Un layout puede leerlo con frameIdPath.

Operación	Comportamiento
set	Establecer un id de frame específico. Los strings simples se tratan como ids literales; {{...}} las templates se resuelven primero.
next	Pasar al siguiente frame desde frameIds o los frames declarados en surface.
previous	Ir al frame anterior.
toggle	Alternar entre los dos primeros frames disponibles, o entre el frame actual y frameId.

Los IDs de frame inválidos se ignoran cuando la mutación tiene una lista de frames seleccionables conocida, manteniendo el estado alineado con la superficie renderizada.

Mutaciones de timer

Las mutaciones del timer apuntan a un timer con nombre desde definition.timers.

Operación	Comportamiento
start / restart	Iniciar desde cero usando la duración actual.
pause	Almacenar el tiempo transcurrido y limpiar startedAt.
resume	Reanudar solo los timers pausados. Los timers detenidos permanecen detenidos hasta un start o restart explícito.
toggle	Pausa un temporizador en ejecución o reanuda uno pausado.
reset	Limpia el tiempo transcurrido y vuelve a idle.
stop	Limpia el progreso de ejecución y marca el temporizador como detenido.
setDuration	Recalcula el estado tras un cambio de duración.

Los bindings del Timer están disponibles para SVG como {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, y campos relacionados.

Opción 2: Sesión de Widget Full-Native

Usa este modo cuando la UI del widget esté construida en code nativo. El plugin proporciona a la app y al widget un registro de sesión compartido y una cola de mensajes.

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

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

Mensajes de Widget Asíncronos

Los mensajes gestionan tareas que requieren una respuesta posterior, como un widget que solicita a la app sincronizar datos.

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

Para fallar el job, pasa error en lugar de response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage es idempotente. Si el mensaje ya está completado o fallido, las llamadas repetidas devuelven el snapshot del mensaje existente.

Detener una sesión nativa

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

Grupos de API

Grupo	APIs
Capacidad	areActivitiesSupported, getPluginVersion
Ciclo de vida de actividad SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Acciones y eventos SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesiones de widgets nativos	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Mensajes de widgets nativos	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fuente de verdad

La referencia completa de tipos está en el repositorio del plugin en src/definitions.ts.

Continúa desde Getting Started

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