Attività in tempo reale Plugin Capacitor

Uso di @capgo/capacitor-live-activities

Interfaccia del plugin Capacitor Live Activities per gestire le Live Activities su iOS.

Installa

bun add @capgo/capacitor-live-activities
bunx cap sync

Setup iOS

L'installazione e la sincronizzazione del plugin non creano l'interfaccia nativa Live Activity. Prima di chiamare startActivity, configura ActivityKit in Xcode:

1. Esegui bunx cap open ios.
2. Aggiungi un Estensione Widget target e abilita Includi Live Activity.
3. Imposta i deployment target dell'app e della Widget Extension a iOS 16.1 o successivi.
4. Assicurati che l'extension sia incorporata nell'app principale.
5. Mantieni un ActivityConfiguration registrato nell'extension WidgetBundle, con Lock Screen e tutte le presentazioni Dynamic Island.
6. Aggiungi NSSupportsLiveActivities al target dell'app principale Info.plist.

<key>NSSupportsLiveActivities</key>
<true/>

Aggiungere solo il target non è sufficiente. L'app nativa o il plugin devono chiamare le API request, update ed end di ActivityKit. La Widget Extension deve contenere code SwiftUI in grado di decodificare e renderizzare lo stesso ActivityAttributes stato e contenuto utilizzati da tali chiamate. Includi i modelli ActivityKit condivisi sia nel target dell'app principale che in quello della Widget Extension. Il template Live Activity generato da Xcode non renderizza automaticamente i layout JSON passati a questo plugin; anche l'estensione necessita di un renderer nativo compatibile.

Immagini condivise

Quando utilizzi i metodi di gestione delle immagini, aggiungi la App Groups capability ai target dell'app principale e della Widget Extension. Abilita lo stesso gruppo su entrambi i target usando l'identificativo esatto richiesto dal plugin:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Le estensioni Live Activity non possono accedere alla rete. Scarica le immagini remote nell'app principale, salvale nell'App Group condiviso con saveImage, e poi fai riferimento all'immagine salvata nel layout. Anche gli asset inclusi nel bundle devono appartenere al target della Widget Extension.

Deep Links e Push Updates

• Registra qualsiasi custom URL scheme utilizzato da behavior.widgetUrl o tapUrl sotto il target principale dell'app Info > URL Types settings.
• Per gli aggiornamenti server-driven, aggiungi la Notifiche push capacità e implementa la gestione dei push-token di ActivityKit con APNs.
• Aggiungi NSSupportsLiveActivitiesFrequentUpdates solo quando l'app richiede aggiornamenti push frequenti tramite ActivityKit.

Abilitare solo la capability Push Notifications non basta; gli aggiornamenti server-driven richiedono la gestione nativa del token e un backend APNs.

ActivityKit limita a 4 KB i dati combinati, statici e dinamici, di Live Activity. La Dynamic Island è visibile solo sui modelli supportati; gli altri dispositivi usano la presentazione sulla schermata di blocco.

Cosa espone questo plugin

• areActivitiesSupported - Verifica se le Live Activities sono supportate su questo dispositivo. Richiede iOS 16.1+ e supporto del dispositivo.
• startActivity - Avvia una nuova Live Activity con il layout e i dati specificati.
• updateActivity - Aggiorna una Live Activity esistente con nuovi dati.
• endActivity - Termina una Live Activity.

Esempio d'uso

areActivitiesSupported

Verifica se le Live Activities sono supportate su questo dispositivo. Richiede iOS 16.1+ e supporto del dispositivo.

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

const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
  console.log('Live Activities are supported!');
} else {
  console.log('Not supported:', reason);
}

startActivity

Avvia una nuova Live Activity con il layout e i dati specificati.

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

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
    ]
  },
  dynamicIslandLayout: {
    expanded: {
      leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
      trailing: { type: 'text', content: '{{eta}}' },
      center: { type: 'text', content: '{{status}}' },
      bottom: { type: 'progress', value: 'progress' }
    },
    compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6
  }
});
console.log('Started activity:', activityId);

updateActivity

Aggiorna una Live Activity esistente con nuovi dati.

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

await CapgoLiveActivities.updateActivity({
  activityId: 'abc123',
  data: {
    status: 'Arrived!',
    eta: 'Now',
    progress: 1.0
  },
  alertConfiguration: {
    title: 'Delivery Update',
    body: 'Your order has arrived!'
  }
});

endActivity

Termina una Live Activity.

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

await CapgoLiveActivities.endActivity({
  activityId: 'abc123',
  data: { status: 'Delivered' },
  dismissalPolicy: 'after',
  dismissAfter: Date.now() + 3600000 // 1 hour from now
});

Riferimento completo

• GitHub: https://github.com/Cap-go/capacitor-live-activities/
• Docs: /docs/plugins/live-activities/

Continua da Usando @capgo/capacitor-live-activities

Se stai usando Uso di @capgo/capacitor-live-activities per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Per iniziare per i dettagli di implementazione nella guida introduttiva, Uso di @capgo/capacitor-video-player per la funzionalità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player per i dettagli di implementazione in @capgo/capacitor-video-player, e Usando @capgo/capacitor-native-navigation per la funzionalità nativa in Usando @capgo/capacitor-native-navigation.