Siri, Shortcuts, Widget e System Intents

Expo ha recentemente rilasciato expo-app-intents, che collega il framework Intent dell'app di Apple a JavaScript: frasi per Siri e Shortcuts, cataloghi di entità runtime, schemi app Apple per Apple Intelligence, indicizzazione Spotlight e una coda nativa per le invocazioni che arrivano prima dell'avvio di JavaScript.

@capgo/capacitor-app-intents è il bridge Capacitor per Apple Intent dell'app: frasi per Siri e Shortcuts (tramite codegen a compile time), cataloghi di entità runtime, indicizzazione Spotlight, azioni rapide sulla Home Screen e una coda di invocazioni in sospeso per i cold start. Widget Kit, Live Activities, Share Target e Intent Launcher coprono ancora adiacenti superfici. Questa pagina illustra come si integrano tra loro, così da poter pubblicare integrazioni di sistema senza mescolare Android Intent API con Apple App Intents.

Mappa rapida

Superficie di sistema	plugin Capgo	Cosa fa davvero il plugin
Widget della Home Screen, Live Activities sulla Lock Screen, Dynamic Island (widget SVG o nativo code)	@capgo/capacitor-widget-kit	Persisti attività template, esegui azioni dichiarative, registra i tap su widget o Live Activity, sincronizza sessioni widget full-native tramite App Groups.
Live Activities con layout JSON ad albero	@capgo/capacitor-live-activities	Avvia, aggiorna e termina le attività ActivityKit da Capacitor; sequenze di timer; immagini condivise in App Group.
Ricevi condivisioni da altre app	@capgo/capacitor-share-target	shareReceived eventi per titolo, testo e file tramite intent Android o una Share Extension iOS con App Group.
Apri le impostazioni o le attività Android; apri gli URL delle impostazioni iOS	@capgo/capacitor-intent-launcher	startActivityAsync, openIOSSettings, openApplication. Questo è hai Apple App Intents.
Frasi Siri, Shortcuts, Spotlight, azioni rapide, coda App Intent	@capgo/capacitor-app-intents	Dispatch bridge, setEntityCatalog, indexSpotlightEntities, setHomeScreenShortcutItems, getPendingInvocations, useAppIntentsListener. iOS 16+.
LLM on-device (Apple Intelligence su iPhone supportati)	@capgo/capacitor-llm	API per chat e modelli. Nessun bridge per App Intent o schema.

Confronto con expo-app-intents

Usa questa tabella per valutare la parità. Le righe contrassegnate come parziali indicano che solo una piccola parte coincide.

capacità di expo-app-intents	Capgo oggi
Azioni personalizzate in Siri e nell'app Comandi con frasi vocali	Sì con @capgo/capacitor-app-intents. Le frasi sono letterali a compile time nel codice Swift generato (AppShortcutsProvider), non stringhe JavaScript a runtime.
I parametri degli Shortcut basati su cataloghi di entità JS (AppEntity, EntityQuery)	Sì con @capgo/capacitor-app-intents tramite setEntityCatalog() e nativi EntityQuery wiring.
Schemi delle app Apple (ad esempio intenti per bozze email per Apple Intelligence)	Parziale. App Intents espone performAppleSchemaTemplate come una coda JavaScript (nessuna Mail nativa API). Implementi l'interfaccia di composizione o i deep link nella tua app.
Indicizzazione Spotlight e contenuto dell'app ricercabile	Sì con @capgo/capacitor-app-intents tramite indexSpotlightEntities() (CSSearchableItem, e anche IndexedEntity su iOS 18+).
Associa i contenuti sullo schermo alle entità per l'intelligenza di sistema	Parziale. Gli Entity catalogs alimentano i parametri di Shortcuts; le API di associazione onscreen non sono ancora esposte.
Coda nativa per le azioni avviate prima che JavaScript sia pronto	Sì per App Intents tramite @capgo/capacitor-app-intents (getPendingInvocations, appIntentInvoked). Share Target e Widget Kit utilizzano ancora i propri modelli di retention per condivisioni ed eventi template.
Pulsanti interattivi di Live Activity o widget tramite App Intents	Parziale. Widget Kit include CapgoTemplateActionIntent e CompleteSetIntent come LiveActivityIntent tipi per template azioni hotspot e workout su iOS 17+. Aggiornano lo stato nativo e l'event log; non espongono frasi Siri arbitrarie da JavaScript.
WidgetKit e ActivityKit dal JavaScript dell'app	Sì. plugin Widget Kit e Live Activities (vedi sotto).
Android Intent azioni (impostazioni, VIEW, SEND e simili)	Sì per l'avvio e la ricezione tramite Intent Launcher e Share Target.

Widget Kit: widget, Live Activities e azioni dei template

@capgo/capacitor-widget-kit è la corrispondenza più vicina a UI visibile dal sistema al di fuori del tuo WebView. Puoi gestire le superfici di Lock Screen e Dynamic Island da Capacitor, renderizzare widget Home Screen da template SVG o nativi Swift/Kotlin code e gestire i tap in un secondo momento.

Avvia una Live Activity da template e gestisci le azioni in JavaScript

Registra un listener all'avvio dell'app, quindi esegui il polling o chiama dopo App resume, poiché i tap sui widget potrebbero avvenire mentre il WebView è ancora in caricamento:

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

Su iOS, i controlli interattivi nell'estensione del widget possono chiamare la versione inclusa di CapgoTemplateActionIntent (LiveActivityIntent). Quel percorso aggiorna lo stato del template memorizzato e aggiunge voci allo stesso event log letto dal tuo JavaScript. È hai lo stesso di aggiungere una frase Shortcut visibile all'utente nell'app Shortcuts.

Vedi Guida introduttiva a Widget Kit per la configurazione di App Group e sessioni widget completamente native.

Live Activities: layout JSON da Capacitor

@capgo/capacitor-live-activities si concentra su ActivityKit con layout JSON dichiarativi (testo, immagini, timer, gauge, regioni Dynamic Island). Non registra App Intents né scorciatoie Siri.

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

Usa Attività in tempo reale quando desideri il DSL del layout e gli helper per le immagini. Scegli Widget Kit quando hai bisogno di widget per la Home, frame SVG o del log degli eventi del template e LiveActivityIntent pulsanti.

Share Target: condivisioni in entrata (non Shortcut in uscita)

@capgo/capacitor-share-target permette ad altre app di inviare contenuti all'interno della tua app. Su iOS aggiungi una Share Extension che scrive in un App Group; il plugin dell'app principale legge e svuota quel payload ed emette shareReceived.

Il cold start è gestito su iOS: il plugin nativo chiama notifyListeners(..., retainUntilConsumed: true) quindi il primo listener JavaScript riceve comunque l'evento.

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

Questo si integra con gli SEND intent filter di Android. Permette di hai pubblicare scorciatoie di condivisione o azioni Siri dalla tua app.

Intent Launcher: intent Android e impostazioni iOS (non App Intents)

Il nome si confonde facilmente con Apple Intent dell'app. @capgo/capacitor-intent-launcher avvia solo Android activity (inclusi ActivityAction.CREATE_SHORTCUT per le scorciatoie legacy del launcher) e apre Impostazioni iOS Schemi URL.

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

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

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

Per Siri, l'app Shortcuts e AppIntent types, usa @capgo/capacitor-app-intents. Intent Launcher avvia solo le activity Android e gli URL delle Impostazioni iOS.

Combinazioni suggerite

Obiettivo	Inizia da qui
Lock Screen e Dynamic Island con SVG e tap logging	Widget Kit
Layout JSON avanzato e sequenze timer	Attività in tempo reale
L'utente condivide un link o un file nella tua app	Target di condivisione
Deep link verso le impostazioni WiFi o dell'app	Launcher di Intent
Frase Siri che esegue il tuo handler JS con parametri entity	Intent dell'app (codegen per le frasi, setEntityCatalog, useAppIntentsListener)

Gap rimanenti (per la pianificazione)

Area	Stato
Widget Kit personalizzato AppShortcut frasi legate al log eventi del template	Widget Kit include ancora LiveActivityIntent solo helper; le frasi Siri arbitrarie vanno nel codegen di App Intents.
Polling Share Target API	Solo eventi oggi; usa addListener('shareReceived') subito all'avvio.
Intent dello schema nativo di Apple Mail	Non disponibile per le app di terze parti; App Intents mette in coda un handler JS.
Parità di App Intents su Android	App Intents è disponibile solo su iOS 16+; Android restituisce un errore chiaro.

Continua

• Panoramica di App Intents
• Panoramica di Widget Kit
• Panoramica di Live Activities
• Panoramica di Share Target
• Panoramica di Intent Launcher