Siri, Shortcuts, Widgets, dan System Intents

Expo baru saja merilis expo-app-intents, yang menghubungkan App Intents framework Apple ke JavaScript: frase Siri dan Shortcuts, katalog entitas runtime, skema aplikasi Apple untuk Apple Intelligence, pengindeksan Spotlight, dan antrean native untuk pemanggilan yang masuk sebelum JavaScript berjalan.

@capgo/capacitor-app-intents adalah bridge Capacitor untuk Apple App Intents: frase Siri dan Shortcuts (via compile time codegen), katalog entitas runtime, pengindeksan Spotlight, quick actions di Home Screen, dan antrean pemanggilan pending untuk cold start. Widget Kit, Live Activities, Share Target, dan Intent Launcher tetap mencakup fitur terkait. Halaman ini menjelaskan cara semuanya bekerja bersama agar Anda bisa merilis integrasi sistem tanpa mencampuradukkan Android Intent API dengan Apple App Intents.

Pemetaan cepat

Antarmuka sistem	plugin Capgo	Fungsi utama plugin ini
Widget Home Screen, Lock Screen Live Activities, Dynamic Island (SVG atau widget native code)	@capgo/capacitor-widget-kit	Simpan template activity, jalankan aksi deklaratif, log ketukan widget atau Live Activity, sinkronisasi sesi widget full-native via App Groups.
Live Activities dengan struktur layout JSON	@capgo/capacitor-live-activities	Mulai, update, dan akhiri activity ActivityKit dari Capacitor; urutan timer; berbagi gambar di App Group.
Terima share dari aplikasi lain	@capgo/capacitor-share-target	shareReceived event untuk judul, teks, dan file via Android intents atau iOS Share Extension plus App Group.
Buka pengaturan atau activity Android; buka URL Settings iOS	@capgo/capacitor-intent-launcher	startActivityAsync, openIOSSettings, openApplication. Ini adalah tidak Apple App Intents.
Frasa Siri, Shortcuts, Spotlight, quick actions, antrean App Intent	@capgo/capacitor-app-intents	Kirim ke bridge, setEntityCatalog, indexSpotlightEntities, setHomeScreenShortcutItems, getPendingInvocations, useAppIntentsListener. iOS 16+.
LLM on-device (Apple Intelligence di iPhone yang didukung)	@capgo/capacitor-llm	API Chat dan model. Tanpa App Intent atau schema bridge.

Perbandingan dengan expo-app-intents

Gunakan tabel ini saat mengevaluasi paritas. Baris bertanda parsial berarti hanya sebagian kecil yang tumpang tindih.

kapabilitas expo-app-intents	Capgo saat ini
Aksi kustom di Siri dan aplikasi Shortcuts dengan frasa suara	Ya dengan @capgo/capacitor-app-intents. Frasa adalah literal waktu kompilasi dalam Swift yang di-generate (AppShortcutsProvider), bukan string JavaScript saat runtime.
Parameter Shortcut yang didukung oleh katalog entitas JS (AppEntity, EntityQuery)	Ya dengan @capgo/capacitor-app-intents melalui setEntityCatalog() dan native EntityQuery koneksi.
Skema aplikasi Apple (misalnya intent draf email untuk Apple Intelligence)	Sebagian. App Intents menyediakan performAppleSchemaTemplate sebagai antrean JavaScript saja (tidak ada API Mail native). Anda mengimplementasikan UI compose atau deep link di aplikasi Anda.
Indeks Spotlight dan konten aplikasi yang dapat dicari	Ya dengan @capgo/capacitor-app-intents melalui indexSpotlightEntities() (CSSearchableItem, serta IndexedEntity pada iOS 18+).
Hubungkan konten layar dengan entitas untuk kecerdasan sistem	Parsial. Katalog entitas mendukung parameter Shortcuts; API asosiasi layar penuh belum tersedia.
Antrean native untuk aksi yang dijalankan sebelum JavaScript siap	Ya untuk App Intents melalui @capgo/capacitor-app-intents (getPendingInvocations, appIntentInvoked). Share Target dan Widget Kit masih menggunakan model retensi sendiri untuk share dan event template.
Interactive Live Activity atau tombol widget via App Intents	Parsial. Widget Kit menyediakan CapgoTemplateActionIntent dan CompleteSetIntent sebagai LiveActivityIntent tipe untuk templat aksi hotspot dan workout di iOS 17+. Aksi ini memperbarui state native dan event log; aksi ini tidak mengekspos frasa Siri arbitrer dari JavaScript.
WidgetKit dan ActivityKit dari JavaScript aplikasi	Ya. Plugin Widget Kit dan Live Activities (lihat di bawah).
Android Intent aksi (settings, VIEW, SEND, dan sejenisnya)	Ya untuk menjalankan dan menerima via Intent Launcher dan Share Target.

Widget Kit: widget, Live Activities, dan template actions

@capgo/capacitor-widget-kit adalah kecocokan terdekat untuk UI yang terlihat sistem di luar WebView Anda. Anda dapat mengontrol permukaan Lock Screen dan Dynamic Island dari Capacitor, merender widget Home Screen dari template SVG atau code Swift/Kotlin native, dan memproses tap setelahnya.

Mulai template Live Activity dan tangani action di JavaScript

Daftarkan listener saat app booting, lalu lakukan polling atau panggil setelah App resume karena tap widget mungkin berjalan saat WebView masih loading:

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

const ACTIVITY_ID = 'order-tracker';

async function drainTemplateEvents() {
  const { events } = await CapgoWidgetKit.listTemplateEvents({
    activityId: ACTIVITY_ID,
    unacknowledgedOnly: true,
  });

  for (const event of events) {
    if (event.actionId === 'mark-delivered') {
      // Update your app state from event.state or event.payload
    }
    await CapgoWidgetKit.acknowledgeTemplateEvents({
      eventIds: [event.eventId],
    });
  }
}

await CapgoWidgetKit.startTemplateActivity({
  activityId: ACTIVITY_ID,
  state: { status: 'On the way' },
  definition: {
    id: 'delivery-card',
    actions: [
      {
        id: 'mark-delivered',
        eventName: 'delivery.marked',
      },
    ],
    layouts: {
      lockScreen: {
        width: 200,
        height: 80,
        svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 80"><text x="8" y="40">{{state.status}}</text></svg>',
        hotspots: [
          {
            id: 'deliver',
            actionId: 'mark-delivered',
            x: 120,
            y: 20,
            width: 70,
            height: 40,
            label: 'Mark delivered',
          },
        ],
      },
    },
  },
});

App.addListener('resume', () => {
  void drainTemplateEvents();
});

void drainTemplateEvents();

Di iOS, kontrol interaktif dalam widget extension dapat memanggil bundle CapgoTemplateActionIntent (LiveActivityIntent). Path tersebut memperbarui state template yang tersimpan dan menambahkannya ke event log yang sama dengan yang dibaca JavaScript Anda. Ini adalah tidak sama dengan menambahkan frasa Shortcut yang terlihat oleh pengguna di aplikasi Shortcuts.

Lihat Memulai dengan Widget Kit untuk setup App Group dan sesi widget full-native.

Live Activities: Layout JSON dari Capacitor

@capgo/capacitor-live-activities berfokus pada ActivityKit dengan layout JSON deklaratif (teks, gambar, timer, gauge, area Dynamic Island). Ini tidak mendaftarkan App Intents atau Siri shortcuts.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported } = await CapgoLiveActivities.areActivitiesSupported();
if (!supported) {
  return;
}

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'vertical',
    children: [
      { type: 'text', content: 'Order {{orderId}}', fontWeight: 'bold' },
      { type: 'text', content: '{{status}}' },
    ],
  },
  data: { orderId: '42', status: 'Preparing' },
});

await CapgoLiveActivities.updateActivity({
  activityId,
  data: { orderId: '42', status: 'Out for delivery' },
});

Pilih Live Activities saat Anda butuh layout DSL dan bantuan gambar. Pilih Widget Kit saat Anda butuh widget Home Screen, frame SVG, atau log event template dan LiveActivityIntent tombol.

Share Target: share masuk (bukan Shortcuts keluar)

@capgo/capacitor-share-target memungkinkan aplikasi lain mengirim konten ke dalam aplikasi Anda. Di iOS, Anda menambahkan Share Extension yang menulis ke App Group; plugin aplikasi utama akan membaca dan menghapus payload tersebut lalu memancarkan shareReceived.

Cold start ditangani di iOS: plugin native memanggil notifyListeners(..., retainUntilConsumed: true) jadi listener JavaScript pertama tetap menerima event tersebut.

import { CapacitorShareTarget } from '@capgo/capacitor-share-target';

await CapacitorShareTarget.addListener('shareReceived', (event) => {
  const firstText = event.texts[0] ?? '';
  const firstFile = event.files[0];
  console.log(event.title, firstText, firstFile?.uri);
});

Ini melengkapi Android SEND intent filters. Hal ini tidak mempublikasikan share shortcuts atau Siri actions dari aplikasi Anda.

Intent Launcher: Android intents dan iOS Settings (bukan App Intents)

Namanya mudah tertukar dengan Apple App Intents. @capgo/capacitor-intent-launcher hanya menjalankan Android aktivitas (termasuk ActivityAction.CREATE_SHORTCUT untuk shortcut launcher lama) dan membuka Pengaturan iOS URL scheme.

import { IntentLauncher, ActivityAction, IOSSettings } from '@capgo/capacitor-intent-launcher';

await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS,
});

await IntentLauncher.openIOSSettings({ option: IOSSettings.App });

Untuk Siri, aplikasi Shortcuts, dan AppIntent tipe, gunakan @capgo/capacitor-app-intents. Intent Launcher hanya menjalankan aktivitas Android dan URL iOS Settings.

Kombinasi yang disarankan

Tujuan	Mulai di sini
Lock Screen plus Dynamic Island dengan SVG dan tap logging	Widget Kit
JSON layout kaya fitur dan urutan timer	Live Activities
User membagikan link atau file ke aplikasi Anda	Bagikan Target
Deep link user ke pengaturan WiFi atau aplikasi	Peluncur Intent
Frasa Siri yang menjalankan JS handler dengan parameter entitas	App Intents (codegen untuk frasa, setEntityCatalog, useAppIntentsListener)

Celah yang tersisa (untuk perencanaan)

Aspek	Status
Widget Kit kustom AppShortcut frasa yang terhubung ke log event template	Widget Kit masih membundel LiveActivityIntent hanya helper; frasa Siri sembarang masuk ke codegen App Intents.
Polling Share Target API	Untuk saat ini hanya event; gunakan addListener('shareReceived') di awal saat boot.
Intent schema Native Apple Mail	Tidak tersedia untuk aplikasi pihak ketiga; App Intents mengantrekan handler JS sebagai gantinya.
Paritas App Intents di Android	App Intents hanya untuk iOS 16+; Android akan mengembalikan error yang jelas.

Lanjut terus

• Ikhtisar App Intents
• Ikhtisar Widget Kit
• Ikhtisar Live Activities
• Ikhtisar Share Target
• Ikhtisar Intent Launcher