Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

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

Impor

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

Mulai cepat

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

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

Contoh: startTemplateActivity

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

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

Contoh: startTemplateWidget

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

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

Kesalahan umum

• Sinkronisasi Native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Setup iOS

Untuk Live Activities dan ekstensi WidgetKit, konfigurasi aplikasi native terlebih dahulu:

• Gunakan iOS 17+ untuk tombol Live Activity interaktif jika memungkinkan.
• Tambah NSSupportsLiveActivities ke aplikasi Info.plist saat menggunakan ActivityKit.
• Tambahkan App Group yang sama ke target app dan target widget extension.
• Atur CapgoWidgetKitAppGroup di keduanya Info.plist file ke identifier App Group yang sama.

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

Cek Dukungan

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

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

Opsi 1: SVG Template Activity

Gunakan mode ini jika widget dapat merender SVG yang sudah di-resolve. Plugin ini menyimpan state, me-resolve placeholder, menerapkan tap action, mengganti frame SVG, dan menjaga konsistensi state 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>`,
          },
        ],
      },
    },
  },
});

Jalankan Action dari Aplikasi

Widget native dapat memicu action yang sama melalui hotspot/action wiring. Aplikasi juga bisa menjalankannya secara langsung:

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

Proses Event Widget

Action memancarkan event agar aplikasi dapat memproses interaksi widget setelah launch atau resume:

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

Di iOS, tombol widget extension dapat memanggil bundled LiveActivityIntent helpers (CapgoTemplateActionIntent) yang menulis ke event log yang sama. Ini terpisah dari phrase Siri shortcut atau aplikasi Shortcuts. Lihat Siri, Shortcuts, dan widget.

Update atau Akhiri Aktivitas

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

Mutasi Frame

Mutasi frame menuliskan id frame aktif ke dalam state. Layout kemudian dapat membacanya dengan frameIdPath.

Operasi	Perilaku
set	Atur id frame tertentu. String biasa dianggap sebagai id frame literal; {{...}} template akan diselesaikan terlebih dahulu.
next	Pindah ke frame berikutnya dari frameIds atau frame yang dideklarasikan pada surface.
previous	Pindah ke frame sebelumnya.
toggle	Toggle antara dua frame pertama yang tersedia, atau antara frame saat ini dan frameId.

ID frame yang tidak valid akan diabaikan jika mutasi memiliki daftar frame yang dapat dipilih, sehingga state tetap selaras dengan tampilan.

Mutasi Timer

Timer mutations menargetkan timer bernama dari definition.timers.

Operasi	Perilaku
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus startedAt.
resume	Lanjutkan hanya timer yang dijeda. Timer yang dihentikan akan tetap berhenti sampai ada perintah start atau restart secara eksplisit.
toggle	Jeda timer yang sedang berjalan atau lanjutkan timer yang dijeda.
reset	Hapus waktu yang telah berlalu dan kembali ke mode idle.
stop	Hapus progres runtime dan tandai timer sebagai berhenti.
setDuration	Hitung ulang status setelah perubahan durasi.

Binding timer tersedia untuk SVG sebagai {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, dan field terkait lainnya.

Opsi 2: Sesi Widget Full-Native

Gunakan mode ini saat UI widget dibangun secara native di code. Plugin ini menyediakan record sesi bersama dan antrean pesan untuk app dan widget.

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

Pesan Widget Async

Messages mencakup pekerjaan yang memerlukan respons di kemudian hari, seperti widget yang meminta aplikasi untuk sinkronisasi data.

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

Untuk menggagalkan job, kirim error alih-alih response:

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

completeWidgetMessage bersifat idempotent. Jika pesan sudah selesai atau gagal, panggilan berulang akan mengembalikan snapshot pesan yang ada.

Hentikan Sesi Native

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

API Grup

Grup	API
Kemampuan	areActivitiesSupported, getPluginVersion
Lifecycle aktivitas SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Aksi dan event SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesi widget Native	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Pesan widget Native	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Sumber Kebenaran

Referensi tipe lengkap ada di repositori plugin di src/definitions.ts.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-widget-kit untuk kapabilitas native saat menggunakan @capgo/capacitor-widget-kit, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.