Getting Started

Installa

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo abilità al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza il seguente prompt:

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

Se preferisci l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

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

iOS Setup

Installando e sincronizzando il plugin non crea l'interfaccia nativa dell'attività in tempo reale. ActivityKit richiede un'estensione Widget che registri una configurazione dell'attività in tempo reale prima di poter visualizzare qualcosa. startActivity può visualizzare qualsiasi cosa.

Requirements

• Usa iOS 16.1 o successivo per entrambi il target dell'app e il target dell'estensione Widget.
• Test on an iOS device or a compatible simulator. The Dynamic Island only appears on supported device models; other devices use the Lock Screen presentation.
• Mantieni i dati statici e dinamici di ActivityKit sotto i 4 KB come richiesto da Apple.

Sezione intitolata “1. Crea un'estensione Widget”

Fenestra del terminale

bunx cap open ios

Poi:

1. Seleziona File > Nuovo > Target.
2. Aggiungi un Estensione del widget.
3. Abilita Includi attività in tempo reale.
4. Disabilita Includi intento di configurazione a meno che l'app non richieda anche un widget configurabile.
5. Assicurati che l'estensione generata sia inclusa nel target dell'app principale.

L'estensione del widget deve contenere un ActivityConfiguration e registrarlo nel suo WidgetBundle. Deve fornire ogni presentazione di attività Live richiesta:

• Schermo bloccato
• Isola dinamica espansa
• Isola Dinamica compatta in avvio e in fine
• Isola dinamica minima

Adding the target alone is not sufficient. The native app or plugin must call ActivityKit’s request, update, and end APIs. The extension must contain SwiftUI code that can decode and render the same ActivityAttributes and content state used by those calls. Include shared ActivityKit models in both the main app and Widget Extension targets. The Xcode-generated Live Activity template does not automatically render the JSON layouts passed to this plugin; the extension also needs a compatible native layout renderer.

2. Abilita le Attività in Tempo Reale

Aggiungi la seguente chiave al target principale dell'app. Info.plist:

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

If il progetto genera i suoi Info.plist, aggiungi Sostiene le attività in tempo reale con un valore booleano di YES sotto le proprietà del target iOS personalizzato del main app target al posto

3. Configura il gruppo di applicazioni per le immagini condivise

Un gruppo di App è richiesto solo quando si utilizza saveImage, removeImage, listImages, o cleanupImages. Il plugin deriva l'identificatore del gruppo di applicazioni dall'identificatore del bundle dell'app principale utilizzando questo formato esatto:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Esempio di un'app con identificatore del bundle com.example.delivery deve utilizzare:

group.com.example.delivery.liveactivities

In Xcode, aggiungi la Gruppi dell'app abilità a entrambi il target dell'app principale e il target dell'estensione Widget, quindi abilita lo stesso identificatore su entrambi i target.

Le estensioni delle attività in tempo reale non possono accedere a rete. Scarica le immagini remote nell'app principale e salvale nel Gruppo App condiviso prima di riferirsi a esse da un'attività in tempo reale. Per le immagini incorporate, abilita anche l'estensione Widget nella partecipazione dei target degli asset.

4. Configura i collegamenti profondi

Quando si utilizza behavior.widgetUrl o una sequenza di timer tapUrlsi deve registrare lo schema di URL corrispondente o il collegamento universale nell'app principale. Per uno schema personalizzato come myapp://order/12345aggiungi lo schema sotto il target dell'app principale Info > Tipi di URL impostazioni.

5. Opzionale: Abilita Aggiornamenti Server-Driver

Gli aggiornamenti locali iniziali dall'app non richiedono le notifiche push. Per iniziare, aggiornare o terminare le attività in tempo reale da un server:

• Aggiungi il Le notifiche push abilità alla app principale di destinazione.
• Ottieni i token di push di ActivityKit e inviali al server.
• Invia notifiche di ActivityKit tramite APNs utilizzando il liveactivity tipo di push.
• Add NSSupportsLiveActivitiesFrequentUpdates al main app Info.plist solo quando il caso d'uso richiede aggiornamenti push frequenti.

I token di aggiornamento push di ActivityKit sono separati dai token di notifica standard per dispositivo. L'abilitazione della capacità delle notifiche push non è sufficiente; gli aggiornamenti server-driven richiedono un trattamento di token nativo e un backend APNs.

Elenco di controllo di configurazione nativa

Prima di chiamare startActivityverificare che

• NSSupportsLiveActivities sia abilitato sul target dell'app principale.
• L'estensione del widget è incorporata e registra un ActivityConfiguration.
• L'implementazione nativa di ActivityKit e l'estensione del widget utilizzano lo stesso ActivityAttributes tipo.
• L'app e i target di distribuzione dell'estensione del widget sono iOS 16.1 o successivi.
• Le attività in tempo reale sono abilitate per l'app nei impostazioni iOS.
• La corrispondente App Group è abilitata su entrambi i target quando si utilizzano immagini condivise.
• Qualsiasi schema di URL personalizzato utilizzato da widgetUrl o tapUrl è registrato.

è registrato.

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

API Overview

areActivitiesSupported

Controlla se le attività in tempo reale 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 attività in tempo reale 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 un'attività in tempo reale 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 un'attività in tempo reale.

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

getAllActivities

Ottieni tutte le attività in tempo reale attualmente attive.

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

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

saveImage

Salva un'immagine nel contenitore condiviso per App Group per utilizzarla nelle attività in tempo reale. Le immagini devono essere salvate nel contenitore condiviso per essere accessibili dall'estensione del widget.

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

const { success, imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-image',
  compressionQuality: 0.8
});
// Use in layout with: { type: 'image', source: 'saved', value: imageName }

removeImage

Rimuovi un'immagine salvata dal contenitore condiviso.

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

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

listImages

Elenco tutte le immagini salvate nel contenitore condiviso.

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

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

cleanupImages

Rimuovi tutte le immagini salvate dal contenitore condiviso.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Avvia una sequenza di timer per allenamenti/sport. Su iOS: Visualizzato nella Live Activity e nell'Isola Dinamica Su Android: Visualizzato come notifica in primo piano con timer

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

const { sequenceId } = await CapgoLiveActivities.startTimerSequence({
  title: 'HIIT Workout',
  steps: [
    { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' },
    { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
  ],
  loop: true,
  loopCount: 3,
  soundEnabled: true,
  vibrateEnabled: true,
  countdownBeeps: true,
  tapUrl: 'myapp://workout/hiit'
});

pauseTimerSequence

Sospendi la sequenza di timer.

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

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

resumeTimerSequence

Riprendi una sequenza di timer sospesa.

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

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

stopTimerSequence

Sospendi e annulla la sequenza di timer.

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

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

skipTimerStep

Saltare al passo successivo nella sequenza.

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

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

previousTimerStep

Torna al passo precedente nella sequenza.

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

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

getTimerState

Ottenere lo stato corrente di una sequenza oraria.

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

const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });
console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);
console.log(`Time remaining: ${state.remainingSeconds}s`);

Riferimento di tipo

AreActivitiesSupportedResult

Risultato della verifica se le attività sono supportate.

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

StartActivityOptions

Opzioni per avviare un'attività in tempo reale.

export interface StartActivityOptions {
  /** Main activity layout (lock screen widget) */
  layout: ActivityLayout;
  /** Dynamic Island layout configuration */
  dynamicIslandLayout: DynamicIslandLayout;
  /** Activity behavior settings */
  behavior?: LiveActivitiesBehavior;
  /** Dynamic data for the activity */
  data: Record<string, unknown>;
  /** Stale date timestamp (activity becomes stale after this) */
  staleDate?: number;
  /** Relevance score for activity ordering (0-100) */
  relevanceScore?: number;
}

StartActivityResult

Risultato dell'avvio di un'attività.

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

UpdateActivityOptions

Opzioni per aggiornare un'attività in tempo reale.

export interface UpdateActivityOptions {
  /** Activity ID to update */
  activityId: string;
  /** Updated data */
  data: Record<string, unknown>;
  /** Optional alert to show with update */
  alertConfiguration?: ActivityAlertConfiguration;
  /** Updated stale date */
  staleDate?: number;
  /** Updated relevance score */
  relevanceScore?: number;
}

EndActivityOptions

Opzioni per la fine di un'attività in diretta.

export interface EndActivityOptions {
  /** Activity ID to end */
  activityId: string;
  /** Final data to display */
  data?: Record<string, unknown>;
  /** Dismissal policy */
  dismissalPolicy?: 'immediate' | 'default' | 'after';
  /** Dismiss after timestamp (when dismissalPolicy is 'after') */
  dismissAfter?: number;
}

GetAllActivitiesResult

Risultato di tutte le attività.

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

SaveImageOptions

Opzioni per la salvaguardia di un'immagine.

export interface SaveImageOptions {
  /** Base64 encoded image data */
  imageData: string;
  /** Name to save the image as */
  name: string;
  /** JPEG compression quality (0-1, default 0.8) */
  compressionQuality?: number;
}

SaveImageResult

Risultato della salvaguardia dell'immagine.

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

RemoveImageOptions

Opzioni per rimuovere un'immagine.

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

RemoveImageResult

Risultato della rimozione di un'immagine.

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

ListImagesResult

Risultato della lista delle immagini.

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

TimerSequenceOptions

Opzioni per avviare una sequenza di timer.

export interface TimerSequenceOptions {
  /** Array of steps in the sequence */
  steps: TimerStep[];
  /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */
  title?: string;
  /** Whether to loop the sequence when complete */
  loop?: boolean;
  /** Number of times to loop (if loop is true, 0 means infinite) */
  loopCount?: number;
  /** Play sound on step change (default: true) */
  soundEnabled?: boolean;
  /** Vibrate on step change (default: true) */
  vibrateEnabled?: boolean;
  /** Play countdown beeps in last 3 seconds (default: true) */
  countdownBeeps?: boolean;
  /** Deep link URL when tapping the notification/activity */
  tapUrl?: string;
  /** Keep screen on during timer (Android only, default: false) */
  keepScreenOn?: boolean;
}

Fonte Di Verità

Questa pagina è generata dal plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Continua da Getting Started

Se stai utilizzando Getting Started per pianificare dashboard e API operazioni, connettilo con Utilizzando @capgo/capacitor-live-attività per la capacità nativa in Utilizzando @capgo/capacitor-live-attività, API Overview per il dettaglio di implementazione in API Overview, Introduzione per il dettaglio di implementazione in Introduzione, API Chiavi per il dettaglio di implementazione in API Chiavi, e Dispositivi per i dettagli di implementazione nei dispositivi.