Getting Started

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

Instalar

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA mediante el siguiente comando:

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

Entonces utilice la siguiente solicitud:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

bun add @capgo/capacitor-background-task
bunx cap sync

iOS Setup

Agregue el modo de procesamiento de fondo y el identificador de tarea permitido ios/App/App/Info.plist:

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

Entonces ejecuta:

bunx cap sync ios

Importar

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

Definir una tarea

Defina el callback en el ámbito del módulo para que se registre tan pronto como la aplicación se inicie 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 es en 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 disparador de prueba en desarrollo o QA. Llama a cada tarea registrada de inmediato.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Desregistrarse De Una Tarea

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Expiración De iOS

iOS puede detener una tarea de fondo antes de que termine tu trabajo de JavaScript. Escucha eventos de expiración 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 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.
• Mantén el trabajo corto e idempotente.
• Persiste cualquier estado que necesites antes de devolver BackgroundTaskResult.Success.
• Evita confiar en tareas de fondo para plazos visibles para el usuario o alarmas.

Sigue adelante desde Empezar

Si estás utilizando Getting Started para planificar el trabajo de plugin nativo, conectarlo con Usando @capgo/capacitor-tarea-de-fondo para la capacidad nativa en Usando @capgo/capacitor-tarea-de-fondo Directorio de Plugins de Capgo para el flujo de trabajo del producto en Directorio de Plugins de Capgo Plugins de Capacitor por Capgo para el detalle de implementación en Plugins de Capacitor por Capgo Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Empresa Ionic para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternativas.