Anleitung zum Starten

Eine Einrichtungsvorlage mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-background-task`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/background-task/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

@capgo/capacitor-background-task lässt ein Capacitor-App regelmäßige Aufgaben für Synchronisierung, Cache-Refreshes, Analytics-Übermittlung und andere Hintergrundabfragen registrieren.

Installieren

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

iOS-Einrichtung

Fügen Sie den Hintergrundverarbeitungsmodus und die zulässige Aufgabenidentifikation hinzu ios/App/App/Info.plist:

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

Dann ausführen:

npx cap sync ios

Importieren

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

Eine Aufgabe definieren

__CAPGO_KEEP_0__

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

Die Auftragsplanung registrieren

Aufrufen registerTaskAsync __CAPGO_KEEP_0__

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

minimumInterval ist in Minuten. Android erzwingt eine Mindestzeit von 15 Minuten. iOS behandelt den Wert als frühesten Beginndatum und kann später laufen.

Status überprüfen

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

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

Ein Testlauf auslösen

Verwenden Sie den Testauslöser im Entwicklungs- oder Qa-Modus. Er ruft alle registrierten Aufgaben sofort auf.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Eine Aufgabe abmelden

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

iOS Ablaufdatum

iOS kann einen Hintergrundauftrag beenden, bevor Ihre JavaScript-Arbeit abgeschlossen ist. Hören Sie sich bei Ablaufereignissen an, wenn Reinigung oder Checkpointing relevant ist.

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

await expiration.remove();

Kompatibilität von Hintergrundaufgaben für React Native

Der Plugin bietet auch eine kleine Kompatibilitätslayer für Apps, die von 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,
});

Produktionshinweise

Hintergrundplanung ist opportun, nicht exakt.
Halten Sie die Arbeit kurz und idempotent.
Behalten Sie alle benötigten Zustände, bevor Sie zurückkehren BackgroundTaskResult.Success.
Vermeiden Sie es, sich auf Hintergrundaufgaben für sichtbare Fristen oder Alarms zu verlassen.