Primeros pasos

@capgo/capacitor-background-task permite que una app de Capacitor registre tareas periódicas para sincronización, refresco de caché, envío de analíticas y otras operaciones de fetch en segundo plano.

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

iOS Setup

Añade el modo de procesamiento en segundo plano y el identificador de tarea permitido 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 ejecuta:

npx cap sync ios

Importar

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

Errores comunes

• Ámbito del módulo: registrar defineTask antes registerTaskAsync.
• ids de iOS: coincide con BGTaskSchedulerPermittedIdentifiers entradas.
• Intervalos: El SO puede retrasar las tareas más allá de minimumInterval.

Definir una tarea

Define el callback en el scope del módulo para que se registre en cuanto el sistema operativo inicie la app.

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 la programación

Llama a registerTaskAsync después de que tu app tenga suficiente contexto para habilitar el background job.

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

minimumInterval está en minutos. Android exige un mínimo de 15 minutos. iOS trata el valor como la fecha de inicio más temprana y puede ejecutarse más tarde.

Verificar el estado

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

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

Lanzar una ejecución de prueba

Usa el disparador de prueba en desarrollo o QA. Llama a cada tarea registrada de inmediato.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Desregistrar una tarea

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Expiración en iOS

iOS puede detener una tarea en segundo plano antes de que termine tu código JavaScript. Escucha los eventos de expiración cuando necesites realizar una limpieza o un checkpoint.

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

await expiration.remove();

Compatibilidad con tareas en background de React Native

El plugin también ofrece una pequeña capa de compatibilidad para apps 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 en segundo plano es oportunista, no exacta.
• Mantén las tareas cortas e idempotentes.
• Persiste cualquier estado que necesites antes de retornar BackgroundTaskResult.Success.
• Evita depender de tareas en segundo plano para plazos o alarmas visibles para el usuario.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el trabajo con plugins nativos, conéctalo con Uso de @capgo/capacitor-background-task para la capacidad nativa en Uso de @capgo/capacitor-background-task, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.