Per iniziare

@capgo/capacitor-background-task permette a un'app Capacitor di registrare job periodici per sincronizzazione, aggiornamento cache, invio analytics e altre operazioni di fetch in background.

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

npm install @capgo/capacitor-background-task
npx cap sync

Setup iOS

Aggiungi la modalità di elaborazione in background e l'identificativo del task consentito a ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>app.capgo.backgroundtask.processing</string>
</array>

Poi esegui:

npx cap sync ios

Importa

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

Errori comuni

• Ambito del modulo: registra defineTask prima registerTaskAsync.
• ID iOS: corrisponde BGTaskSchedulerPermittedIdentifiers voci.
• Intervalli: l'OS potrebbe ritardare i job oltre minimumInterval.

Definire un task

Definisci la callback a livello di modulo, così verrà registrata non appena l'app viene avviata dal sistema operativo.

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

const SYNC_TASK = 'sync-offline-data';

BackgroundTask.defineTask(SYNC_TASK, async () => {
  try {
    await fetch('https://api.example.com/sync', { method: 'POST' });
    return BackgroundTaskResult.Success;
  } catch {
    return BackgroundTaskResult.Failed;
  }
});

Registrare la pianificazione

Chiama registerTaskAsync dopo che l'app ha acquisito abbastanza contesto per abilitare il background job.

await BackgroundTask.registerTaskAsync(SYNC_TASK, {
  minimumInterval: 30,
  requiresNetwork: true,
});

minimumInterval è in minuti. Android impone un minimo di 15 minuti. iOS tratta il valore come data di inizio minima e potrebbe eseguirlo più tardi.

Controlla lo stato

const status = await BackgroundTask.getStatusAsync();
const isRegistered = await BackgroundTask.isTaskRegisteredAsync(SYNC_TASK);
const registeredTasks = await BackgroundTask.getRegisteredTasksAsync();

console.log({ status, isRegistered, registeredTasks });

Avvia un test

Usa il trigger di test in sviluppo o QA. Esegue immediatamente ogni task registrata.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Rimuovi un task

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Scadenza su iOS

iOS può interrompere un background task prima che il tuo codice JavaScript finisca. Ascolta gli eventi di expiration quando è necessario eseguire cleanup o checkpoint.

const expiration = await BackgroundTask.addExpirationListener((event) => {
  console.warn('Background task expired', event.taskName, event.taskId);
});

await expiration.remove();

Compatibilità con React Native Background Task

Il plugin espone anche un piccolo layer di compatibilità per le app che migrano da react-native-background-task.

import { BackgroundTask } from '@capgo/capacitor-background-task';

BackgroundTask.define(async () => {
  await fetch('https://api.example.com/sync', { method: 'POST' });
});

await BackgroundTask.schedule({
  period: 1800,
});

Note per la produzione

• La pianificazione dei background task è opportunistica, non precisa.
• Mantieni il lavoro breve e idempotente.
• Persisti qualsiasi stato necessario prima di terminare BackgroundTaskResult.Success.
• Evita di affidarti ai background task per scadenze o allarmi visibili all'utente.

Continua da Getting Started

Se stai usando Per iniziare per pianificare il lavoro sui plugin nativi, collegalo a Utilizzo di @capgo/capacitor-background-task per la funzionalità nativa in Utilizzo di @capgo/capacitor-background-task, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.