@capgo/capacitor-background-task

Overview

Define module scope tasks, schedule intervals, and return results the OS understands for sync and cache warming.

Platform support

Platform	Support	Notes
iOS	Yes	BGTaskScheduler identifiers in Info.plist
Android	Yes	WorkManager style jobs
Web	No	Use service workers

Core Capabilities

• defineTask - Register the JavaScript callback for a named task.
• registerTaskAsync - Persist and schedule a periodic task.
• unregisterTaskAsync - Cancel future runs for one task.
• isTaskRegisteredAsync - Check whether a task is registered.
• getRegisteredTasksAsync - List currently registered task names.
• getPendingTaskRunsAsync - Inspect native task events recorded before JavaScript was ready.
• getStatusAsync - Check native background task availability.
• triggerTaskWorkerForTestingAsync - Run registered tasks immediately during development.
• addExpirationListener - Handle iOS expiration callbacks.
• define, schedule, cancel, statusAsync, and finish - Compatibility helpers for react-native-background-task.

Platform Behavior

Background tasks are not exact timers. Android and iOS decide when to run scheduled work based on battery, network, app usage, and system policy.

Platform	Native scheduler	Important behavior
Android	WorkManager	Periodic work has a 15-minute minimum interval.
iOS	BGTaskScheduler	minimumInterval is an earliest begin date, not a guaranteed cadence.
Web	Test-only fallback	No real background scheduler is available.

Public API

Method	Description
defineTask	Defines the JavaScript callback for a named task.
registerTaskAsync	Registers a named periodic background task.
unregisterTaskAsync	Cancels future task runs.
isTaskRegisteredAsync	Returns whether a task is registered.
getRegisteredTasksAsync	Lists registered task names.
getPendingTaskRunsAsync	Lists native task events waiting to be finished.
getStatusAsync	Returns whether native background scheduling is available.
triggerTaskWorkerForTestingAsync	Triggers registered tasks for development and QA.
addExpirationListener	Listens for iOS expiration events.

Source Of Truth

This reference is synced from src/definitions.ts in capacitor-background-task.

Keep going from @capgo/capacitor-background-task

If you are using @capgo/capacitor-background-task to plan native plugin work, connect it with Using @capgo/capacitor-background-task for the native capability in Using @capgo/capacitor-background-task, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.