Inizia

Installa

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

Importa

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

Configurazione iOS

Per le attività in tempo reale e le estensioni di WidgetKit, configurare l'app nativa per primo:

• Usa iOS 17+ per i pulsanti di attività interattivi quando possibile.
• Aggiungi NSSupportsLiveActivities alla tua app Info.plist quando si utilizza ActivityKit.
• Aggiungi lo stesso Gruppo di Applicazione al target dell'app e al target dell'estensione di widget.
• Imposta CapgoWidgetKitAppGroup in entrambi Info.plist i file al identificatore del Gruppo di Applicazione condiviso.

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

Verifica il supporto

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

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

Opzione 1: Attività di template SVG

Utilizza questo modo quando il widget può renderizzare l'SVG risolto. Il plugin memorizza lo stato, risolve i placeholder, applica le azioni di tap, passa alle frame SVG e mantiene lo stato del timer coerente.

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

Esegui azioni dal'app

I widget nativi possono attivare le stesse azioni attraverso la loro configurazione hotspot/action. L'app può anche eseguirle direttamente:

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

Processare gli eventi dei widget

Gli azioni emettono eventi in modo che l'app possa elaborare le interazioni dei widget dopo l'avvio o il ripristino:

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

Aggiorna o termina l'attività

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

Mutazioni del frame

Le mutazioni del frame scrivono l'ID del frame attivo nello stato. Un layout può poi leggerlo con frameIdPath.

Operazione	Comportamento
set	Imposta un ID di frame specifico. Le stringhe piane vengono trattate come ID di frame letterali; {{...}} i template vengono risolti per primi.
next	Muoviti al prossimo frame da frameIds o dai frame dichiarati su surface.
previous	Muoviti al frame precedente.
toggle	Alternare tra i primi due frame disponibili, o tra il frame corrente e frameId.

Gli ID di frame non validi vengono ignorati quando la mutazione ha una lista di frame selezionabili nota, quindi lo stato rimane allineato con la superficie visualizzata.

Mutazioni del timer

Le mutazioni del timer mirano a un timer denominato da definition.timers.

Operazione	Comportamento
start / restart	Inizia da zero utilizzando la durata corrente.
pause	Memorizza il tempo trascorso e cancella startedAt.
resume	Riprendi solo i timer sospesi. I timer fermati restano fermati fino a un avvio esplicito o riavvio.
toggle	Sospendi un timer in esecuzione o riprendi un timer sospeso.
reset	Cancella il tempo trascorso e torna allo stato di attesa.
stop	Cancella il progresso di esecuzione e segna il timer come fermato.
setDuration	Ricalcola lo stato dopo un cambio di durata.

Le legature del timer sono disponibili per SVG come {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}} e campi correlati.

Opzione 2: Sessione del widget nativo a piena capacità

Utilizza questo modo quando l'interfaccia del widget è costruita in nativo code. Il plugin fornisce al'app e al widget un registro di sessione condiviso e una coda di messaggi.

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

Messaggi widget asincroni

I messaggi coprono il lavoro che richiede una risposta successiva, come un widget che chiede all'app di sincronizzare i dati.

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

Per fallire il lavoro, passa error invece di response:

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

completeWidgetMessage È idempotente. Se il messaggio è già completato o fallito, le chiamate ripetute restituiscono lo snapshot del messaggio esistente.

Interrompi una sessione nativa

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

API Gruppi

Gruppo	API
Capacità	areActivitiesSupported, getPluginVersion
Ciclo di vita dell'attività SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Azioni e eventi SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sessioni widget native	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Messaggi widget native	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fonte di Verità

La riferimento di tipo completo vive nel repository del plugin su src/definitions.ts.