Iniziare

Installa

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

Configurazione iOS

L'installazione e la sincronizzazione del plugin non creano l'interfaccia nativa dell'attività in tempo reale. ActivityKit richiede un'estensione del widget che registra una configurazione dell'attività in tempo reale prima di poterla visualizzare. startActivity Requisiti

Sottosezione intitolata “Requisiti”

• Testa l'app su un dispositivo iOS o un simulatore compatibile. L'isola dinamica si visualizza solo su modelli di dispositivi supportati; gli altri dispositivi utilizzano la presentazione della schermata di blocco.
• Conserva i dati statici e dinamici di ActivityKit al di sotto del limite di 4 KB stabilito da Apple.
• 1. Crea un'estensione del widget

2. Registra una configurazione dell'attività in tempo reale nell'estensione del widget

Apre il progetto iOS nativo:

bunx cap open ios

Poi:

1. Scegli File > Nuovo > Target.
2. Aggiungi un Estensione di widget.
3. Abilita Includi l'attività in tempo reale.
4. Disabilita Includi la configurazione dell'intento se l'app non richiede anche un widget configurabile.
5. Assicurati che l'estensione generata sia incorporata nel target principale dell'app.

L'Estensione del Widget deve contenere un ActivityConfiguration e registrarlo nel suo WidgetBundle. Deve fornire ogni presentazione di attività in tempo reale richiesta:

• Schermo bloccato
• Isola Dinamica espansa
• Isola Dinamica compatto e condotto
• Isola Dinamica minima

Aggiungere solo il target non è sufficiente. L'app nativa o il plugin devono chiamare le API di richiesta, aggiornamento e fine di ActivityKit. L'estensione deve contenere SwiftUI code che possono decodificare e rendere lo stesso ActivityAttributes e stato di contenuto utilizzato da quelle chiamate. Includi i modelli condivisi di ActivityKit in entrambi i target dell'app principale e dell'Estensione del Widget. Il template di attività in tempo reale generato da Xcode non rende automaticamente le layout JSON passate a questo plugin; l'estensione ha anche bisogno di un renderer di layout nativo compatibile.

2. Abilita le attività in tempo reale

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

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

Se il progetto genera le sue Info.plist, aggiungi Supporta le attività in tempo reale con un valore booleano di YES sotto le proprietà del target iOS personalizzato del target principale dell'app

3. Configura il gruppo dell'app per le immagini condivise

Un gruppo dell'app è richiesto solo quando si utilizza saveImage, removeImage, listImagesEseguire il comando, o cleanupImagesCopia nel portapenne

group.<MAIN_APP_BUNDLE_ID>.liveactivities

deve utilizzare: com.example.delivery Copia nel portapenne

group.com.example.delivery.liveactivities

capacità di gruppo App a entrambi i target dell'app principale e dell'estensione Widget, quindi abilita lo stesso identificatore su entrambi i target. Gli estensioni di 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

Sottosezione intitolata “4. Configura i collegamenti profondi”

When utilizzando behavior.widgetUrl o una sequenza di timer tapUrl, registrare lo schema di URL o l'Universal Link nel main app. Per uno schema personalizzato come myapp://order/12345, aggiungere lo schema sotto le impostazioni Info > Tipi di URL del main app target.

5. Facoltativo: Attivare Aggiornamenti Server-Driven

Il push non è richiesto per gli aggiornamenti locali iniziali dall'app. Per iniziare, aggiornare o terminare le attività in diretta da un server:

• Aggiungere il Push Notifications capacità al main app target.
• Ottenere i token di push di ActivityKit e inviarli al server.
• Invia notifiche di ActivityKit attraverso APNs utilizzando il tipo di push. liveactivity Aggiungi
• al main app NSSupportsLiveActivitiesFrequentUpdates solo quando il caso d'uso richiede aggiornamenti di push frequenti. Info.plist Il token di push di ActivityKit sono separati dai token di dispositivo di notifica standard degli utenti. Abilitando la capacità delle notifiche push da solo non è sufficiente; gli aggiornamenti server-driven richiedono un trattamento nativo dei token e un backend APNs.

Elenco di controllo di configurazione nativa

Sezione intitolata “Elenco di controllo di configurazione nativa”

, verificare che: startActivityè abilitato sul target dell'app principale.

• NSSupportsLiveActivities Capgo
• L'estensione del Widget è incorporata e registra un ActivityConfiguration.
• L'implementazione nativa di ActivityKit e l'estensione del Widget utilizzano lo stesso ActivityAttributes tipo.
• Gli obiettivi di distribuzione dell'app e dell'estensione del Widget sono iOS 16.1 o successivi.
• Le attività Live sono abilitate per l'app nei impostazioni iOS.
• Il gruppo di app corrispondente è abilitato su entrambi gli obiettivi quando si utilizzano immagini condivise.
• Qualsiasi schema di URL personalizzato utilizzato da widgetUrl o tapUrl è registrato.

Importa

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

API Panoramica

areActivitiesSupported

Verifica 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 diretta.

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 diretta 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 di gruppo condiviso per utilizzarla nelle attività in diretta. 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

Elencare 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

Eliminare 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: Mostra in Live Activity e Dynamic Island Su Android: Mostra come una 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

Sospendere 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

Interrompi e ignora la sequenza di timer.

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

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

skipTimerStep

Saltare al passaggio successivo nella sequenza.

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

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

previousTimerStep

Torna al passaggio precedente nella sequenza.

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

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

getTimerState

Ottieni lo stato corrente di una sequenza di timer.

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 diretta.

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 l'aggiornamento di 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 tempo reale.

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 getAllActivities.

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 salvataggio di un'immagine.

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

RemoveImageOptions

Opzioni per la rimozione di 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 l'avvio di 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;
}

Punto di riferimento

Questa pagina è generata dal plugin. src/definitions.tsRiepilogo quando le informazioni pubbliche API cambiano in fase di sincronizzazione.

Continua da Inizia a utilizzare

Se stai utilizzando Inizia a utilizzare per pianificare il dashboard e le API operazioni, connettilo con Usando @capgo/capacitor-live-attività per la capacità nativa in Usando @capgo/capacitor-live-attività, Panoramica di API per la dettaglio di implementazione in Panoramica di API, Introduzione per il dettaglio di implementazione in Introduzione, Chiavi di API per il dettaglio di implementazione in Chiavi di API, e Dispositivi per il dettaglio di implementazione in Dispositivi.