Prise en main

@capgo/capacitor-background-task permet à une application Capacitor d'enregistrer des tâches périodiques pour la synchronisation, le rafraîchissement du cache, l'envoi d'analytics et d'autres opérations de fetch en arrière-plan.

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque 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, lancez :

npx cap sync ios

Importer

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

Erreurs courantes

• Portée du module : enregistrer defineTask avant registerTaskAsync.
• ids iOS : correspondre BGTaskSchedulerPermittedIdentifiers entrées.
• Intervalles : l'OS peut retarder les tâches au-delà de minimumInterval.

Définir une tâche

Définissez le callback au niveau du module pour 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 la planification

Appelez registerTaskAsync une fois que votre application dispose d'assez de contexte pour activer la tâche de fond.

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

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

Vérifier le statut

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

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

Lancer un test

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

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Désenregistrer une tâche

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Expiration sur iOS

Sur iOS, un background task peut être interrompu avant la fin de votre code JavaScript. Écoutez les événements d’expiration si le nettoyage ou le checkpoint est important.

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

await expiration.remove();

Compatibilité des tâches de fond React Native

Le plugin expose également une petite couche de compatibilité pour les applications en cours de migration depuis 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 en arrière-plan est opportuniste, pas exacte.
• Gardez le travail court et idempotent.
• Persistez tout l’état dont vous avez besoin avant de revenir BackgroundTaskResult.Success.
• Évitez de vous fier aux tâches en arrière-plan pour les échéances ou alarmes visibles par l’utilisateur.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le travail sur les plugins natifs, connectez-l’à Utilisation de @capgo/capacitor-background-task pour la fonctionnalité native dans Utilisation de @capgo/capacitor-background-task, Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.