Démarrage

@capgo/capacitor-background-task permet à une application Capacitor s'inscrire pour des tâches de synchronisation, des mises à jour de cache, des envois d'analytiques et d'autres opérations de récupération de fond.

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les compétences Capgo à votre outil d'IA en utilisant la commande suivante :

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

Ensuite, utilisez la commande suivante :

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

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

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

Configuration iOS

Ajoutez le mode de traitement en arrière-plan et l'identifiant de tâche autorisé à ios/App/App/Info.plist:

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

Ensuite, exécutez :

npx cap sync ios

Importer

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

Définir une tâche

Définir l'appel de retour au niveau du module afin qu'il soit enregistré dès que l'application est lancée par le système d'exploitation.

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;
  }
});

Enregistrer Le Planning

Appeler registerTaskAsync après que votre application dispose d'un contexte suffisant pour activer le travail en arrière-plan.

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

minimumInterval est en minutes. Android impose un minimum de 15 minutes. iOS traite la valeur comme une date de début la plus tôt et peut exécuter plus tard.

Vérifier l'état

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

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

Déclencher une Exécution de Test

Utilisez le déclencheur de test en développement ou en QA. Il appelle chaque tâche enregistrée immédiatement.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Désinscrire une Tâche

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Expiration de l'iOS

iOS peut interrompre une tâche de fond avant que votre travail JavaScript ne se termine. Écoutez les événements d'expiration lorsqu'il s'agit de nettoyage ou de point de contrôle.

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

await expiration.remove();

Compatibilité de la tâche de fond de React Native

Le plugin expose également une petite couche de compatibilité pour les applications en train de migrer vers 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,
});

Notes de production

• La planification de fond est opportuniste, pas exacte.
• Maintenez les tâches courtes et idempotentes.
• Conservez tout l'état dont vous avez besoin avant de renvoyer BackgroundTaskResult.Success.
• Évitez de vous fier aux tâches de fond pour les échéances ou les alarmes visibles de l'utilisateur.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le travail de plugin natif, connectez-le avec Utiliser @capgo/capacitor-task de fond pour la capacité native dans Utiliser @capgo/capacitor-task de fond, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Ajouter ou Mettre à Jour des Plugins pour le détail d'implémentation dans Ajouter ou Mettre à Jour des Plugins, et Alternatives de Plugins Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugins Entreprise Ionic.