Empezar

@capgo/capacitor-background-task permite que una aplicación Capacitor se registre para tareas periódicas de sincronización, refrescos de caché, entrega de análisis y otras operaciones de recuperación de fondo.

Instalación

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

Configuración de iOS

Agregue el modo de procesamiento de fondo y el identificador de tarea permitida 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>

Luego ejecute:

npx cap sync ios

Importar

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

Definir una tarea

Define la llamada a función en el ámbito del módulo para que se registre tan pronto como se inicie la aplicación por parte del 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;
  }
});

Registrar El Horario

Llamar registerTaskAsync después de que tu aplicación tenga suficiente contexto para habilitar el trabajo de fondo.

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

minimumInterval dura __CAPGO_KEEP_0__ minutos. Android impone un mínimo de 15 minutos. iOS trata el valor como una fecha de inicio más temprana y puede ejecutarse más tarde.

Ver Estado

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

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

Desencadenar una Ejecución de Prueba

Utilice el desencadenante de prueba en desarrollo o QA. Llama a cada tarea registrada de inmediato.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Deshabilitar una Tarea

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Vencimiento de iOS

iOS puede detener una tarea de fondo antes de que termine su trabajo de JavaScript. Escuche eventos de vencimiento cuando importa la limpieza o el punto de control.

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

await expiration.remove();

Compatibilidad de la tarea de fondo de React Native

El plugin también expone una pequeña capa de compatibilidad para aplicaciones que migran desde 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,
});

Notas de producción

• La programación de fondo es oportunista, no exacta.
• Mantenga el trabajo corto y idempotente.
• Mantén cualquier estado que necesites antes de regresar BackgroundTaskResult.Success.
• Evita confiar en tareas de fondo para plazos o alarmas visibles para el usuario.