BackgroundFetch¶

configure¶

static Future<int> configure(BackgroundFetchConfig config, Function(String) onFetch, [Function(String)? onTimeout])

Configure the plugin and begin listening for background-fetch events.

Calling configure automatically starts background-fetch (equivalent to calling BackgroundFetch.start immediately after configuration).

The BackgroundFetchConfig.minimumFetchInterval option controls how frequently iOS will wake your app in the background. Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports additional scheduling constraints such as requiredNetworkType, requiresCharging, etc.

Warning

You must call BackgroundFetch.finish within your event callback. Failure to do so will result in the OS throttling future background events for your app.

Basic configuration

int status = await BackgroundFetch.configure(BackgroundFetchConfig(
  minimumFetchInterval: 15,
), (String taskId) async {
  print('[BackgroundFetch] taskId: $taskId');
  BackgroundFetch.finish(taskId);
}, (String taskId) {
  print('[BackgroundFetch] TIMEOUT: $taskId');
  BackgroundFetch.finish(taskId);
});

print('[BackgroundFetch] status: $status');

Android configuration

BackgroundFetch.configure(BackgroundFetchConfig(
  minimumFetchInterval: 15,
  stopOnTerminate: false,
  startOnBoot: true,
  enableHeadless: true,
  requiresBatteryNotLow: true,
), (String taskId) async {
  print('[BackgroundFetch] taskId: $taskId');
  BackgroundFetch.finish(taskId);
}, (String taskId) {
  BackgroundFetch.finish(taskId);
});

finish¶

static Future<void> finish(String taskId)

Signal to the OS that your background task is complete.

Warning

You must call finish at the end of every background-fetch event callback. Failure to call finish has serious consequences:

iOS — The OS may terminate your app and penalise future background-wake frequency.
Android — The JobScheduler job will not be considered complete and the OS may throttle or block future executions.

Always call finish as quickly as possible, even when your task encounters an error. For timeout events, call finish immediately without doing any additional work. Example

BackgroundFetch.configure(BackgroundFetchConfig(), (String taskId) async {
  try {
    await doMyWork();
  } catch (e) {
    print('Error: $e');
  } finally {
    BackgroundFetch.finish(taskId);
  }
}, (String taskId) {
  BackgroundFetch.finish(taskId);
});

registerHeadlessTask Android only¶

static Future<bool> registerHeadlessTask(Function(HeadlessEvent) callback)

Register a function to execute when the app is terminated while background-fetch events remain active.

Requires stopOnTerminate false and enableHeadless true.

How it works¶

When Android terminates the app, the native module launches a minimal JS context (without the React Native UI) and invokes your headless task function. This allows you to handle background events even when the app is not running.

Registration¶

Call registerHeadlessTask at your app's entry point (index.js), outside any React component. The registration must happen before the OS attempts to fire a headless event.

Restrictions¶

Do not import modules that depend on the React Native UI runtime (e.g. components, navigation, Redux stores that render UI).
Keep the task lightweight — the OS may kill the JS context at any time.
Always call BackgroundFetch.finish before the returned Promise resolves. Example

// main.dart — register at the top level, annotated with @pragma.
@pragma('vm:entry-point')
void backgroundFetchHeadlessTask(HeadlessEvent task) async {
  String taskId = task.taskId;
  bool isTimeout = task.timeout;

  if (isTimeout) {
    BackgroundFetch.finish(taskId);
    return;
  }
  print('[BackgroundFetch] Headless event, taskId: $taskId');
  // ... perform lightweight work ...
  BackgroundFetch.finish(taskId);
}

void main() {
  BackgroundFetch.registerHeadlessTask(backgroundFetchHeadlessTask);
  runApp(MyApp());
}

scheduleTask¶

static Future<bool> scheduleTask(TaskConfig config)

Schedule a custom one-shot or periodic background task in addition to the default fetch event registered with BackgroundFetch.configure.

Custom tasks fire the same onEvent callback registered in BackgroundFetch.configure, identified by their TaskConfig.taskId. Call BackgroundFetch.finish with that taskId to signal completion, and BackgroundFetch.stop with the taskId to cancel.

iOS¶

On iOS, custom tasks are registered using the BGProcessingTask API. You must declare each taskId in your app's Info.plist under BGTaskSchedulerPermittedIdentifiers before calling scheduleTask.

Android¶

Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports all AbstractConfig scheduling constraints. One-shot task

BackgroundFetch.scheduleTask(TaskConfig(
  taskId: 'com.foo.customtask',
  delay: 5000,
  stopOnTerminate: false,
));

Periodic task

BackgroundFetch.scheduleTask(TaskConfig(
  taskId: 'com.foo.periodic-sync',
  delay: 600000,
  periodic: true,
  requiredNetworkType: BackgroundFetch.NETWORK_TYPE_ANY,
  requiresNetworkConnectivity: true,
));

start¶

static Future<int> start()

Start subscribing to background-fetch events.

BackgroundFetch.configure calls start automatically. Use start explicitly only after a previous call to BackgroundFetch.stop. Example

int status = await BackgroundFetch.start();
print('[BackgroundFetch] started, status: $status');

status¶

static Future<int> get status

Query the current authorization status of the Background Fetch API.

Value	Constant	Description
`0`	BackgroundFetchStatus.STATUS_RESTRICTED	Background fetch updates are unavailable and the user cannot enable them again (e.g. parental controls).
`1`	BackgroundFetchStatus.STATUS_DENIED	The user explicitly disabled background behavior for this app or the whole system.
`2`	BackgroundFetchStatus.STATUS_AVAILABLE	Background fetch is available and enabled.
Example

int status = await BackgroundFetch.status;
switch (status) {
  case BackgroundFetch.STATUS_RESTRICTED:
    print('Background fetch restricted');
    break;
  case BackgroundFetch.STATUS_DENIED:
    print('Background fetch denied by user');
    break;
  case BackgroundFetch.STATUS_AVAILABLE:
    print('Background fetch available');
    break;
}

stop¶

static Future<int> stop([String? taskId])

Stop subscribing to background-fetch events.

If a taskId is provided, only that specific scheduled task is cancelled.
If no taskId is provided, all background-fetch and scheduled tasks are cancelled.

Use BackgroundFetch.start to resume after stopping. Example

// Stop all background-fetch events.
await BackgroundFetch.stop();

// Stop a single scheduled task by taskId.
await BackgroundFetch.stop('com.foo.customtask');